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