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 15 16 .LP 17 .nf 18 \fBsvc:/system/svc/restarter:default\fR 19 .fi 20 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 87 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 112 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 131 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 140 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 156 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 190 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 215 216 .RE 217 218 .RE 219 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 229 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 240 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 278 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 291 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 304 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 333 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 346 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 357 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 380 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 392 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 404 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 415 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 427 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 515 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 525 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 535 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 553 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 563 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: 570 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 582 583 .sp 584 .LP 585 This request will take effect on the next restart of \fBsvc.startd\fR. 586 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)