Print this page
12071 clarify implementation of single_instance in SMF services
Reviewed by: Robert Mustacchi <rm@fingolfin.org>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1m/svc.startd.1m.man.txt
+++ new/usr/src/man/man1m/svc.startd.1m.man.txt
1 1 SVC.STARTD(1M) Maintenance Commands SVC.STARTD(1M)
2 2
3 3
4 4
5 5 NAME
6 6 svc.startd - Service Management Facility master restarter
7 7
8 8 SYNOPSIS
9 9 /lib/svc/bin/svc.startd
10 10
11 11
12 12 svc:/system/svc/restarter:default
13 13
14 14
15 15 DESCRIPTION
16 16 svc.startd is the master restarter daemon for Service Management
17 17 Facility (SMF) and the default restarter for all services. svc.startd
18 18 starts, stops, and restarts services based on administrative requests,
19 19 system failures, or application failures.
20 20
21 21
22 22 svc.startd maintains service state, as well as being responsible for
23 23 managing faults in accordance with the dependencies of each service.
24 24
25 25
26 26 svc.startd is invoked automatically during system startup. It is
27 27 restarted if any failures occur. svc.startd should never be invoked
28 28 directly.
29 29
30 30
31 31 See smf_restarter(5) for information on configuration and behavior
32 32 common to all restarters.
33 33
34 34
35 35 svcs(1) reports status for all services managed by the Service
36 36 Configuration Facility. svcadm(1M) allows manipulation of service
37 37 instances with respect to the service's restarter.
38 38
39 39 Environment Variables
40 40 Environment variables with the "SMF_" prefix are reserved and may be
41 41 overwritten.
42 42
43 43
44 44 svc.startd supplies the "SMF_" environment variables specified in
45 45 smf_method(5) to the method. PATH is set to "/usr/sbin:/usr/bin" by
46 46 default. By default, all other environment variables supplied to
47 47 svc.startd are those inherited from init(1M).
48 48
49 49
50 50 Duplicate entries are reduced to a single entry. The value used is
51 51 undefined. Environment entries that are not prefixed with "<name>="
52 52 are ignored.
53 53
54 54 Restarter Options
55 55 svc.startd is not configured by command line options. Instead,
56 56 configuration is read from the service configuration repository. You
57 57 can use svccfg(1M) to set all options and properties.
58 58
59 59
60 60 The following configuration variables in the options property group are
61 61 available to developers and administrators:
62 62
63 63 boot_messages
64 64
65 65 An astring (as defined in scf_value_is_type; see
66 66 scf_value_is_type(3SCF)) that describes the default level of
67 67 messages to print to the console during boot. The supported message
68 68 options include quiet and verbose. The quiet option prints minimal
69 69 messages to console during boot. The verbose option prints a single
70 70 message per service started to indicate success or failure. You can
71 71 use the boot -m option to override the boot_messages setting at
72 72 boot time. See kernel(1M).
73 73
74 74
75 75 logging
76 76
77 77 Control the level of global service logging for svc.startd. An
78 78 astring (as defined in scf_value_is_type; see
79 79 scf_value_is_type(3SCF)) that describes the default level of
80 80 messages to log to syslog (see syslog(3C) and svc.startd's global
81 81 logfile, /var/svc/log/svc.startd.log. The supported message options
82 82 include quiet, verbose, and debug. The quiet option sends error
83 83 messages requiring administrative intervention to the console,
84 84 syslog and svc.startd's global logfile. The verbose option sends
85 85 error messages requiring administrative intervention to the
86 86 console, syslog and svc.startd's global logfile, and information
87 87 about errors which do not require administrative intervention to
88 88 svc.startd's global logfile. A single message per service started
89 89 is also sent to the console. The debug option sends svc.startd
90 90 debug messages to svc.startd's global logfile, error messages
91 91 requiring administrative intervention to the console, syslog and
92 92 svc.startd's global logfile, and a single message per service
93 93 started to the console.
94 94
95 95
96 96 milestone
97 97
98 98 An FMRI which determines the milestone used as the default boot
99 99 level. Acceptable options include only the major milestones:
100 100
101 101 svc:/milestone/single-user:default
102 102 svc:/milestone/multi-user:default
103 103 svc:/milestone/multi-user-server:default
104 104
105 105
106 106 or the special values all or none. all represents an idealized
107 107 milestone that depends on every service. none is a special
108 108 milestone where no services are running apart from the master
109 109 svc:/system/svc/restarter:default. By default, svc.startd uses all,
110 110 a synthetic milestone that depends on every service. If this
111 111 property is specified, it overrides any initdefault setting in
112 112 inittab(4).
113 113
114 114
115 115 system/reconfigure
116 116
117 117 Indicates that a reconfiguration reboot has been requested.
118 118 Services with actions that must key off of a reconfiguration reboot
119 119 may check that this property exists and is set to 1 to confirm a
120 120 reconfiguration boot has been requested.
121 121
122 122 This property is managed by svc.startd and should not be modified
123 123 by the administrator.
124 124
125 125
126 126
127 127 Configuration errors, such as disabling svc.startd are logged by
128 128 syslog, but ignored.
129 129
130 130 SERVICE STATES
131 131 Services managed by svc.startd can appear in any of the states
132 132 described in smf(5). The state definitions are unmodified by this
133 133 restarter.
134 134
135 135 SERVICE REPORTING
136 136 In addition to any logging done by the managed service, svc.startd
137 137 provides a common set of service reporting and logging mechanisms.
138 138
139 139
140 140 Reporting properties svc.startd updates a common set of properties on
141 141 all services it manages. These properties are a common interface that
142 142 can be used to take action based on service instance health. The
143 143 svcs(1) command can be used to easily display these properties.
144 144
145 145 restarter/state
146 146 restarter/next_state
147 147
148 148 The current and next (if currently in transition) state for an
149 149 instance.
150 150
151 151
152 152 restarter/auxiliary_state
153 153
154 154 A caption detailing additional information about the current
155 155 instance state. The auxiliary state available for services managed
156 156 by svc.startd is:
157 157
158 158 maintenance
159 159
160 160 fault_threshold_reached
161 161 stop_method_failed
162 162 administrative_request
163 163
164 164
165 165
166 166
167 167
168 168 restarter/state_timestamp
169 169
170 170 The time when the current state was reached.
171 171
172 172
173 173 restarter/contract
174 174
175 175 The primary process contract ID, if any, that under which the
176 176 service instance is executing.
177 177
178 178
179 179
180 180 Logs
181 181
182 182
183 183 By default, svc.startd provides logging of significant restarter
184 184 actions for the service as well as method standard output and standard
185 185 error file descriptors to /var/svc/log/service:instance.log. The level
186 186 of logging to system global locations like /var/svc/log/svc.startd.log
187 187 and syslog is controlled by the options/logging property.
188 188
189 189 SERVICE DEFINITION
190 190 When developing or configuring a service managed by svc.startd, a
191 191 common set of properties are used to affect the interaction between the
192 192 service instance and the restarter.
193 193
194 194
195 195 Methods
196 196
197 197
198 198 The general form of methods for the fork/exec model provided by
199 199 svc.startd are presented in smf_method(5). The following methods are
200 200 supported as required or optional by services managed by svc.startd.
201 201
202 202 refresh
203 203 Reload any appropriate configuration parameters from the
204 204 repository or config file, without interrupting service.
205 205 This is often implemented using SIGHUP for system daemons.
206 206 If the service is unable to recognize configuration changes
207 207 without a restart, no refresh method is provided.
208 208
209 209 This method is optional.
210 210
211 211
212 212 start
213 213 Start the service. Return success only after the application
214 214 is available to consumers. Fail if a conflicting instance is
215 215 already running, or if the service is unable to start.
216 216
217 217 This method is required.
218 218
219 219
220 220 stop
221 221 Stop the service. In some cases, the stop method can be
222 222 invoked when some or all of the service has already been
223 223 stopped. Only return an error if the service is not entirely
224 224 stopped on method return.
225 225
226 226 This method is required.
227 227
228 228
229 229
230 230 If the service does not need to take any action in a required method,
231 231 it must specify the :true token for that method.
232 232
233 233
234 234 svc.startd honors any method context specified for the service or any
235 235 specific method. The method expansion tokens described in smf_method(5)
236 236 are available for use in all methods invoked by svc.startd.
237 237
238 238
239 239 Properties
240 240
241 241
242 242 An overview of the general properties is available in smf(5). The
243 243 specific way in which these general properties interacts with
244 244 svc.startd follows:
245 245
246 246 general/enabled
247 247
248 248 If enabled is set to true, the restarter attempts to start the
249 249 service once all its dependencies are satisfied. If set to false,
250 250 the service remains in the disabled state, not running.
251 251
252 252
|
↓ open down ↓ |
252 lines elided |
↑ open up ↑ |
253 253 general/restarter
254 254
255 255 If this FMRI property is empty or set to
256 256 svc:/system/svc/restarter:default, the service is managed by
257 257 svc.startd. Otherwise, the restarter specified is responsible (once
258 258 it is available) for managing the service.
259 259
260 260
261 261 general/single_instance
262 262
263 - If single_instance is set to true, svc.startd only allows one
264 - instance of this service to transition to online or degraded at any
265 - time.
263 + This was originally supposed to ensure that only one service
264 + instance could be in online or degraded state at once; however, it
265 + was never implemented, and is often incorrectly specified in multi-
266 + instance manifests. As such, it should be considered obsolete and
267 + not specified in new manifests.
266 268
267 269
268 270
269 271 Additionally, svc.startd managed services can define the optional
270 272 properties listed below in the startd property group.
271 273
272 274 startd/critical_failure_count
273 275 startd/critical_failure_period
274 276
275 277 The critical_failure_count and critical_failure_period properties
276 278 together specify the maximum number of service failures allowed in
277 279 a given time interval before svc.startd transitions the service to
278 280 maintenance. If the number of failures exceeds
279 281 critical_failure_count in any period of critical_failure_period
280 282 seconds, svc.startd will transition the service to maintenance.
281 283
282 284
283 285 startd/duration
284 286
285 287 The duration property defines the service's model. It can be set to
286 288 transient, child also known as "wait" model services, or contract
287 289 (the default).
288 290
289 291
290 292 startd/ignore_error
291 293
292 294 The ignore_error property, if set, specifies a comma-separated list
293 295 of ignored events. Legitimate string values in that list are core
294 296 and signal. The default is to restart on all errors.
295 297
296 298
297 299 startd/need_session
298 300
299 301 The need_session property, if set to true, indicates that the
300 302 instance should be launched in its own session. The default is not
301 303 to do so.
302 304
303 305
304 306 startd/utmpx_prefix
305 307
306 308 The utmpx_prefix string property defines that the instance requires
307 309 a valid utmpx entry prior to start method execution. The default is
308 310 not to create a utmpx entry.
309 311
310 312
311 313 SERVICE FAILURE
312 314 svc.startd assumes that a method has failed if it returns a non-zero
313 315 exit code or if fails to complete before the timeout specified expires.
314 316 If $SMF_EXIT_ERR_CONFIG or $SMF_EXIT_ERR_FATAL is returned, svc.startd
315 317 immediately places the service in the maintenance state. For all other
316 318 failures, svc.startd places the service in the offline state. If a
317 319 service is offline and its dependencies are satisfied, svc.startd tries
318 320 again to start the service (see smf(5)).
319 321
320 322
321 323 If a contract or transient service does not return from its start
322 324 method before its defined timeout elapses, svc.startd sends a SIGKILL
323 325 to the method, and returns the service to the offline state.
324 326
325 327
326 328 If three failures happen in a row, or if the service is restarting more
327 329 than once a second, svc.startd places the service in the maintenance
328 330 state.
329 331
330 332
331 333 The conditions of service failure are defined by a combination of the
332 334 service model (defined by the startd/duration property) and the value
333 335 of the startd/ignore_error property.
334 336
335 337
336 338 A contract model service fails if any of the following conditions
337 339 occur:
338 340
339 341 o all processes in the service exit
340 342
341 343 o any processes in the service produce a core dump
342 344
343 345 o a process outside the service sends a service process a
344 346 fatal signal (for example, an administrator terminates a
345 347 service process with the pkill command)
346 348
347 349
348 350 The last two conditions may be ignored by the service by specifying
349 351 core and/or signal in startd/ignore_error.
350 352
351 353
352 354 Defining a service as transient means that svc.startd does not track
353 355 processes for that service. Thus, the potential faults described for
354 356 contract model services are not considered failures for transient
355 357 services. A transient service only enters the maintenance state if one
356 358 of the method failure conditions occurs.
357 359
358 360
359 361 "Wait" model services are restarted whenever the child process
360 362 associated with the service exits. A child process that exits is not
361 363 considered an error for "wait" model services, and repeated failures do
362 364 not lead to a transition to maintenance state. However, a wait service
363 365 which is repeatedly exiting with an error that exceeds the default rate
364 366 (5 failures/second) will be throttled back so that the service only
365 367 restarts once per second.
366 368
367 369 LEGACY SERVICES
368 370 svc.startd continues to provide support for services invoked during the
369 371 startup run level transitions. Each /etc/rc?.d directory is processed
370 372 after all managed services which constitute the equivalent run level
371 373 milestone have transitioned to the online state. Standard init scripts
372 374 placed in the /etc/rc?.d directories are run in the order of their
373 375 sequence numbers.
374 376
375 377
376 378 The milestone to run-level mapping is:
377 379
378 380 milestone/single-user
379 381
380 382 Single-user (S)
381 383
382 384
383 385 milestone/multi-user
384 386
385 387 Multi-user (2)
386 388
387 389
388 390 milestone/multi-user-server
389 391
390 392 Multi-user with network services (3)
391 393
392 394
393 395
394 396 Additionally, svc.startd gives these legacy services visibility in SMF
395 397 by inserting an instance per script into the repository. These legacy
396 398 instances are visible using standard SMF interfaces such as svcs(1),
397 399 always appear in the LEGACY-RUN state, cannot be modified, and can not
398 400 be specified as dependencies of other services. The initial start time
399 401 of the legacy service is captured as a convenience for the
400 402 administrator.
401 403
402 404 FILES
403 405 /var/svc/log
404 406 Directory where svc.startd stores log files.
405 407
406 408
407 409 /etc/svc/volatile
408 410 Directory where svc.startd stores log files in
409 411 early stages of boot, before /var is mounted read-
410 412 write.
411 413
412 414
413 415 EXAMPLE
414 416 Example 1 Turning on Verbose Logging
415 417
416 418
417 419 To turn on verbose logging, type the following:
418 420
419 421
420 422 # /usr/sbin/svccfg -s system/svc/restarter:default
421 423 svc:/system/svc/restarter:default> addpg options application
422 424 svc:/system/svc/restarter:default> setprop options/logging = \
423 425 astring: verbose
424 426 svc:/system/svc/restarter:default> exit
425 427
426 428
427 429
428 430
429 431 This request will take effect on the next restart of svc.startd.
|
↓ open down ↓ |
154 lines elided |
↑ open up ↑ |
430 432
431 433
432 434 SEE ALSO
433 435 svcs(1), svcprop(1), kernel(1M), init(1M), svcadm(1M), svccfg(1M),
434 436 svc.configd(1M), setsid(2), syslog(3C), libscf(3LIB),
435 437 scf_value_is_type(3SCF), contract(4), init.d(4), process(4),
436 438 inittab(4), attributes(5), smf(5), smf_method(5)
437 439
438 440
439 441
440 - March 18, 2011 SVC.STARTD(1M)
442 + December 11, 2019 SVC.STARTD(1M)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX