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