/
svc.startd.1m
507 lines (473 loc) · 16.8 KB
/
svc.startd.1m
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2011, Joyent Inc
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH svc.startd 1M "5 May 2008" "SunOS 5.11" "System Administration Commands"
.SH NAME
svc.startd \- Service Management Facility master restarter
.SH SYNOPSIS
.LP
.nf
\fB/lib/svc/bin/svc.startd\fR
.fi
.LP
.nf
\fBsvc:/system/svc/restarter:default\fR
.fi
.SH DESCRIPTION
.sp
.LP
\fBsvc.startd\fR is the master restarter daemon for Service Management Facility (SMF) and the default restarter for all services. \fBsvc.startd\fR starts, stops, and restarts services based on administrative requests, system failures, or application failures.
.sp
.LP
\fBsvc.startd\fR maintains service state, as well as being responsible for managing faults in accordance with the dependencies of each service.
.sp
.LP
\fBsvc.startd\fR is invoked automatically during system startup. It is restarted if any failures occur. \fBsvc.startd\fR should never be invoked directly.
.sp
.LP
See \fBsmf_restarter\fR(5) for information on configuration and behavior common to all restarters.
.sp
.LP
\fBsvcs\fR(1) reports status for all services managed by the Service Configuration Facility. \fBsvcadm\fR(1M) allows manipulation of service instances with respect to the service's restarter.
.SS "Environment Variables"
.sp
.LP
Environment variables with the "SMF_" prefix are reserved and may be overwritten.
.sp
.LP
\fBsvc.startd\fR supplies the "SMF_" environment variables specified in \fBsmf_method\fR(5) to the method. PATH is set to "\fB/usr/sbin:/usr/bin\fR" by default. By default, all other environment variables supplied to \fBsvc.startd\fR are those inherited from \fBinit\fR(1M).
.sp
.LP
Duplicate entries are reduced to a single entry. The value used is undefined. Environment entries that are not prefixed with "<\fIname\fR>=" are ignored.
.SS "Restarter Options"
.sp
.LP
\fBsvc.startd\fR is not configured by command line options. Instead, configuration is read from the service configuration repository. You can use \fBsvccfg\fR(1M) to set all options and properties.
.sp
.LP
The following configuration variables in the \fBoptions\fR property group are available to developers and administrators:
.sp
.ne 2
.mk
.na
\fB\fBboot_messages\fR\fR
.ad
.sp .6
.RS 4n
An \fIastring\fR (as defined in \fBscf_value_is_type\fR; see \fBscf_value_is_type\fR(3SCF)) that describes the default level of messages to print to the console during boot. The supported message options include \fBquiet\fR and \fBverbose\fR. The \fBquiet\fR option prints minimal messages to console during boot. The \fBverbose\fR option prints a single message per service started to indicate success or failure. You can use the \fBboot\fR \fB-m\fR option to override the \fBboot_messages\fR setting at boot time. See \fBkernel\fR(1M).
.RE
.sp
.ne 2
.mk
.na
\fB\fBlogging\fR\fR
.ad
.sp .6
.RS 4n
Control the level of global service logging for \fBsvc.startd\fR. An \fIastring\fR (as defined in \fBscf_value_is_type\fR; see \fBscf_value_is_type\fR(3SCF)) that describes the default level of messages to log to \fBsyslog\fR (see \fBsyslog\fR(3C) and \fBsvc.startd\fR's global logfile, \fB/var/svc/log/svc.startd.log\fR. The supported message options include \fBquiet\fR, \fBverbose\fR, and \fBdebug\fR. The \fBquiet\fR option sends error messages requiring administrative intervention to the console, \fBsyslog\fR and \fBsvc.startd\fR's global logfile. The \fBverbose\fR option sends error messages requiring administrative intervention to the console, \fBsyslog\fR and \fBsvc.startd\fR's global logfile, and information about errors which do not require administrative intervention to \fBsvc.startd\fR's global logfile. A single message per service started is also sent to the console. The \fBdebug\fR option sends \fBsvc.startd\fR debug messages to \fBsvc.startd\fR's global logfile, error messages requiring administrative intervention to the console, \fBsyslog\fR and \fBsvc.startd\fR's global logfile, and a single message per service started to the console.
.RE
.sp
.ne 2
.mk
.na
\fB\fBmilestone\fR\fR
.ad
.sp .6
.RS 4n
An FMRI which determines the milestone used as the default boot level. Acceptable options include only the major milestones:
.sp
.in +2
.nf
svc:/milestone/single-user:default
svc:/milestone/multi-user:default
svc:/milestone/multi-user-server:default
.fi
.in -2
.sp
or the special values \fBall\fR or \fBnone\fR. \fBall\fR represents an idealized milestone that depends on every service. \fBnone\fR is a special milestone where no services are running apart from the master \fBsvc:/system/svc/restarter:default\fR. By default, \fBsvc.startd\fR uses \fBall\fR, a synthetic milestone that depends on every service. If this property is specified, it overrides any \fBinitdefault\fR setting in \fBinittab\fR(4).
.RE
.sp
.ne 2
.mk
.na
\fB\fBsystem/reconfigure\fR\fR
.ad
.sp .6
.RS 4n
Indicates that a reconfiguration reboot has been requested. Services with actions that must key off of a reconfiguration reboot may check that this property exists and is set to 1 to confirm a reconfiguration boot has been requested.
.sp
This property is managed by \fBsvc.startd\fR and should not be modified by the administrator.
.RE
.sp
.LP
Configuration errors, such as disabling \fBsvc.startd\fR are logged by \fBsyslog\fR, but ignored.
.SS "SERVICE STATES"
.sp
.LP
Services managed by \fBsvc.startd\fR can appear in any of the states described in \fBsmf\fR(5). The state definitions are unmodified by this restarter.
.SS "SERVICE REPORTING"
.sp
.LP
In addition to any logging done by the managed service, \fBsvc.startd\fR provides a common set of service reporting and logging mechanisms.
.sp
.LP
Reporting properties \fBsvc.startd\fR updates a common set of properties on all services it manages. These properties are a common interface that can be used to take action based on service instance health. The \fBsvcs\fR(1) command can be used to easily display these properties.
.sp
.ne 2
.mk
.na
\fB\fBrestarter/state\fR\fR
.ad
.br
.na
\fB\fBrestarter/next_state\fR\fR
.ad
.sp .6
.RS 4n
The current and next (if currently in transition) state for an instance.
.RE
.sp
.ne 2
.mk
.na
\fB\fBrestarter/auxiliary_state\fR\fR
.ad
.sp .6
.RS 4n
A caption detailing additional information about the current instance state. The auxiliary state available for services managed by \fBsvc.startd\fR is:
.sp
.ne 2
.mk
.na
\fBmaintenance\fR
.ad
.RS 15n
.rt
.sp
.in +2
.nf
fault_threshold_reached
stop_method_failed
administrative_request
.fi
.in -2
.sp
.RE
.RE
.sp
.ne 2
.mk
.na
\fB\fBrestarter/state_timestamp\fR\fR
.ad
.sp .6
.RS 4n
The time when the current state was reached.
.RE
.sp
.ne 2
.mk
.na
\fB\fBrestarter/contract\fR\fR
.ad
.sp .6
.RS 4n
The primary process contract ID, if any, that under which the service instance is executing.
.RE
.sp
.LP
\fBLogs\fR
.sp
.LP
By default, \fBsvc.startd\fR provides logging of significant restarter actions for the service as well as method standard output and standard error file descriptors to \fB/var/svc/log/\fIservice\fR:\fIinstance\fR.log\fR. The level of logging to system global locations like \fB/var/svc/log/svc.startd.log\fR and \fBsyslog\fR is controlled by the \fBoptions/logging\fR property.
.SS "SERVICE DEFINITION"
.sp
.LP
When developing or configuring a service managed by \fBsvc.startd\fR, a common set of properties are used to affect the interaction between the service instance and the restarter.
.sp
.LP
\fBMethods\fR
.sp
.LP
The general form of methods for the fork/exec model provided by \fBsvc.startd\fR are presented in \fBsmf_method\fR(5). The following methods are supported as required or optional by services managed by \fBsvc.startd\fR.
.sp
.ne 2
.mk
.na
\fB\fBrefresh\fR\fR
.ad
.RS 11n
.rt
Reload any appropriate configuration parameters from the repository or \fBconfig\fR file, without interrupting service. This is often implemented using \fBSIGHUP\fR for system daemons. If the service is unable to recognize configuration changes without a restart, no refresh method is provided.
.sp
This method is optional.
.RE
.sp
.ne 2
.mk
.na
\fB\fBstart\fR\fR
.ad
.RS 11n
.rt
Start the service. Return success only after the application is available to consumers. Fail if a conflicting instance is already running, or if the service is unable to start.
.sp
This method is required.
.RE
.sp
.ne 2
.mk
.na
\fB\fBstop\fR\fR
.ad
.RS 11n
.rt
Stop the service. In some cases, the stop method can be invoked when some or all of the service has already been stopped. Only return an error if the service is not entirely stopped on method return.
.sp
This method is required.
.RE
.sp
.LP
If the service does not need to take any action in a required method, it must specify the \fB:true\fR token for that method.
.sp
.LP
\fBsvc.startd\fR honors any method context specified for the service or any specific method. The method expansion tokens described in \fBsmf_method\fR(5) are available for use in all methods invoked by \fBsvc.startd\fR.
.sp
.LP
\fBProperties\fR
.sp
.LP
An overview of the general properties is available in \fBsmf\fR(5). The specific way in which these general properties interacts with \fBsvc.startd\fR follows:
.sp
.ne 2
.mk
.na
\fB\fBgeneral/enabled\fR\fR
.ad
.sp .6
.RS 4n
If enabled is set to true, the restarter attempts to start the service once all its dependencies are satisfied. If set to false, the service remains in the disabled state, not running.
.RE
.sp
.ne 2
.mk
.na
\fB\fBgeneral/restarter\fR\fR
.ad
.sp .6
.RS 4n
If this FMRI property is empty or set to \fBsvc:/system/svc/restarter:default\fR, the service is managed by \fBsvc.startd\fR. Otherwise, the restarter specified is responsible (once it is available) for managing the service.
.RE
.sp
.ne 2
.mk
.na
\fB\fBgeneral/single_instance\fR\fR
.ad
.sp .6
.RS 4n
If \fBsingle_instance\fR is set to true, \fBsvc.startd\fR only allows one instance of this service to transition to online or degraded at any time.
.RE
.sp
.LP
Additionally, \fBsvc.startd\fR managed services can define the optional properties listed below in the \fBstartd\fR property group.
.sp
.ne 2
.mk
.na
\fB\fBstartd/critical_failure_count\fR
.ad
.br
.na
\fBstartd/critical_failure_period\fR\fR
.ad
.sp .6
.RS 4n
The \fBcritical_failure_count\fR and \fBcritical_failure_period\fR properties together specify the maximum number of service failures allowed in a given time interval before \fBsvc.startd\fR transitions the service to maintenance. If the number of failures exceeds \fBcritical_failure_count\fR in any period of \fBcritical_failure_period\fR seconds, \fBsvc.startd\fR will transition the service to maintenance.
.RE
.sp
.ne 2
.mk
.na
\fB\fBstartd/duration\fR\fR
.ad
.sp .6
.RS 4n
The \fBduration\fR property defines the service's model. It can be set to \fBtransient\fR, \fBchild\fR also known as "\fBwait\fR" model services, or \fBcontract\fR (the default).
.RE
.sp
.ne 2
.mk
.na
\fB\fBstartd/ignore_error\fR\fR
.ad
.sp .6
.RS 4n
The \fBignore_error\fR property, if set, specifies a comma-separated list of ignored events. Legitimate string values in that list are \fBcore\fR and \fBsignal\fR. The default is to restart on all errors.
.RE
.sp
.ne 2
.mk
.na
\fB\fBstartd/need_session\fR\fR
.ad
.sp .6
.RS 4n
The \fBneed_session\fR property, if set to true, indicates that the instance should be launched in its own session. The default is not to do so.
.RE
.sp
.ne 2
.mk
.na
\fB\fBstartd/utmpx_prefix\fR\fR
.ad
.sp .6
.RS 4n
The \fButmpx_prefix\fR string property defines that the instance requires a valid \fButmpx\fR entry prior to start method execution. The default is not to create a \fButmpx\fR entry.
.RE
.SS "SERVICE FAILURE"
.sp
.LP
\fBsvc.startd\fR assumes that a method has failed if it returns a non-zero exit code or if fails to complete before the timeout specified expires. If \fB$SMF_EXIT_ERR_CONFIG\fR or \fB$SMF_EXIT_ERR_FATAL\fR is returned, \fBsvc.startd\fR immediately places the service in the maintenance state. For all other failures, \fBsvc.startd\fR places the service in the offline state. If a service is offline and its dependencies are satisfied, \fBsvc.startd\fR tries again to start the service (see \fBsmf\fR(5)).
.sp
.LP
If a contract or transient service does not return from its start method before its defined timeout elapses, \fBsvc.startd\fR sends a \fBSIGKILL\fR to the method, and returns the service to the offline state.
.sp
.LP
If three failures happen in a row, or if the service is restarting more than once a second, \fBsvc.startd\fR places the service in the maintenance state.
.sp
.LP
The conditions of service failure are defined by a combination of the service model (defined by the \fBstartd/duration\fR property) and the value of the \fBstartd/ignore_error\fR property.
.sp
.LP
A contract model service fails if any of the following conditions occur:
.RS +4
.TP
.ie t \(bu
.el o
all processes in the service exit
.RE
.RS +4
.TP
.ie t \(bu
.el o
any processes in the service produce a core dump
.RE
.RS +4
.TP
.ie t \(bu
.el o
a process outside the service sends a service process a fatal signal (for example, an administrator terminates a service process with the \fBpkill\fR command)
.RE
.sp
.LP
The last two conditions may be ignored by the service by specifying core and/or signal in \fBstartd/ignore_error\fR.
.sp
.LP
Defining a service as transient means that \fBsvc.startd\fR does not track processes for that service. Thus, the potential faults described for contract model services are not considered failures for transient services. A transient service only enters the maintenance state if one of the method failure conditions occurs.
.sp
.LP
"\fBWait\fR" model services are restarted whenever the child process associated with the service exits. A child process that exits is not considered an error for "\fBwait\fR" model services, and repeated failures do not lead to a transition to maintenance state.
.SS "LEGACY SERVICES"
.sp
.LP
\fBsvc.startd\fR continues to provide support for services invoked during the startup run level transitions. Each \fB/etc/rc?.d\fR directory is processed after all managed services which constitute the equivalent run level milestone have transitioned to the online state. Standard \fBinit\fR scripts placed in the \fB/etc/rc?.d\fR directories are run in the order of their sequence numbers.
.sp
.LP
The milestone to run-level mapping is:
.sp
.ne 2
.mk
.na
\fB\fBmilestone/single-user\fR\fR
.ad
.sp .6
.RS 4n
Single-user (\fBS\fR)
.RE
.sp
.ne 2
.mk
.na
\fB\fBmilestone/multi-user\fR\fR
.ad
.sp .6
.RS 4n
Multi-user (\fB2\fR)
.RE
.sp
.ne 2
.mk
.na
\fB\fBmilestone/multi-user-server\fR\fR
.ad
.sp .6
.RS 4n
Multi-user with network services (\fB3\fR)
.RE
.sp
.LP
Additionally, \fBsvc.startd\fR gives these legacy services visibility in SMF by inserting an instance per script into the repository. These legacy instances are visible using standard SMF interfaces such as \fBsvcs\fR(1), always appear in the \fBLEGACY-RUN\fR state, cannot be modified, and can not be specified as dependencies of other services. The initial start time of the legacy service is captured as a convenience for the administrator.
.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/var/svc/log\fR\fR
.ad
.RS 21n
.rt
Directory where \fBsvc.startd\fR stores log files.
.RE
.sp
.ne 2
.mk
.na
\fB\fB/etc/svc/volatile\fR\fR
.ad
.RS 21n
.rt
Directory where \fBsvc.startd\fR stores log files in early stages of boot, before \fB/var\fR is mounted read-write.
.RE
.SH EXAMPLE
.LP
\fBExample 1 \fRTurning on Verbose Logging
.sp
.LP
To turn on verbose logging, type the following:
.sp
.in +2
.nf
# /usr/sbin/svccfg -s system/svc/restarter:default
svc:/system/svc/restarter:default> addpg options application
svc:/system/svc/restarter:default> setprop options/logging = \e
astring: verbose
svc:/system/svc/restarter:default> exit
.fi
.in -2
.sp
.sp
.LP
This request will take effect on the next restart of \fBsvc.startd\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i)
lw(2.75i) |lw(2.75i)
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
AvailabilitySUNWcsu
.TE
.SH SEE ALSO
.sp
.LP
\fBsvcs\fR(1), \fBsvcprop\fR(1), \fBkernel\fR(1M), \fBinit\fR(1M), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M), \fBsvc.configd\fR(1M), \fBsetsid\fR(2), \fBsyslog\fR(3C), \fBlibscf\fR(3LIB), \fBscf_value_is_type\fR(3SCF), \fBcontract\fR(4), \fBinit.d\fR(4), \fBprocess\fR(4), \fBinittab\fR(4), \fBattributes\fR(5), \fBsmf\fR(5), \fBsmf_method\fR(5)