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