1svc.startd(1M) System Administration Commands svc.startd(1M)
2
6 svc.startd - Service Management Facility master restarter
7
9 /lib/svc/bin/svc.startd
10 svc:/system/svc/restarter:default
13
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 svc.startd maintains service state, as well as being responsible for
23 managing faults in accordance with the dependencies of each service.
24 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 See smf_restarter(5) for information on configuration and behavior com‐
32 mon to all restarters.
33 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 Environment Variables
40 Environment variables with the "SMF_" prefix are reserved and may be
41 overwritten.
42 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 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 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 The following configuration variables in the options property group are
61 available to developers and administrators:
62 boot_messages
64 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 logging
76 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 milestone
97 An FMRI which determines the milestone used as the default boot
99 level. Acceptable options include only the major milestones:
100 svc:/milestone/single-user:default
102 svc:/milestone/multi-user:default
103 svc:/milestone/multi-user-server:default
104 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 system/reconfigure
115 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 This property is managed by svc.startd and should not be modified
122 by the administrator.
123 Configuration errors, such as disabling svc.startd are logged by sys‐
127 log, but ignored.
128 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 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 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 restarter/state
145 restarter/next_state
146 The current and next (if currently in transition) state for an
148 instance.
149 restarter/auxiliary_state
152 A caption detailing additional information about the current
154 instance state. The auxiliary state available for services managed
155 by svc.startd is:
156 maintenance
158 fault_threshold_reached
159 stop_method_failed
160 administrative_request
161 restarter/state_timestamp
167 The time when the current state was reached.
169 restarter/contract
172 The primary process contract ID, if any, that under which the ser‐
174 vice instance is executing.
175 Logs
179 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 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 Methods
194 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 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 This method is optional.
207 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 This method is required.
214 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 This method is required.
222 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 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 Properties
235 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 general/enabled
242 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 general/restarter
249 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 general/single_instance
257 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 Additionally, svc.startd managed services can define the optional prop‐
265 erties listed below in the startd property group.
266 startd/duration
268 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 startd/ignore_error
275 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 startd/need_session
282 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 startd/utmpx_prefix
289 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 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 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 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 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 A contract model service fails if any of the following conditions
321 occur:
322 o all processes in the service exit
324 o any processes in the service produce a core dump
326 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 The last two conditions may be ignored by the service by specifying
333 core and/or signal in startd/ignore_error.
334 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 "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 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 The milestone to run-level mapping is:
358 milestone/single-user
360 Single-user (S)
362 milestone/multi-user
365 Multi-user (2)
367 milestone/multi-user-server
370 Multi-user with network services (3)
372 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 /etc/svc/volatile Directory where svc.startd stores log files in
388 early stages of boot, before /var is mounted read-
389 write.
390
393 Example 1 Turning on Verbose Logging
394 To turn on verbose logging, type the following:
397 # /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 This request will take effect on the next restart of svc.startd.
409
412 See attributes(5) for descriptions of the following attributes:
413 ┌─────────────────────────────┬─────────────────────────────┐
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)
428SunOS 5.11 5 May 2008 svc.startd(1M)