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