SVC.STARTD(1M) Maintenance Commands SVC.STARTD(1M) NNAAMMEE svc.startd - Service Management Facility master restarter SSYYNNOOPPSSIISS //lliibb//ssvvcc//bbiinn//ssvvcc..ssttaarrttdd ssvvcc:://ssyysstteemm//ssvvcc//rreessttaarrtteerr::ddeeffaauulltt DDEESSCCRRIIPPTTIIOONN ssvvcc..ssttaarrttdd is the master restarter daemon for Service Management Facility (SMF) and the default restarter for all services. ssvvcc..ssttaarrttdd starts, stops, and restarts services based on administrative requests, system failures, or application failures. ssvvcc..ssttaarrttdd maintains service state, as well as being responsible for managing faults in accordance with the dependencies of each service. ssvvcc..ssttaarrttdd is invoked automatically during system startup. It is restarted if any failures occur. ssvvcc..ssttaarrttdd should never be invoked directly. See ssmmff__rreessttaarrtteerr(5) for information on configuration and behavior common to all restarters. ssvvccss(1) reports status for all services managed by the Service Configuration Facility. ssvvccaaddmm(1M) allows manipulation of service instances with respect to the service's restarter. EEnnvviirroonnmmeenntt VVaarriiaabblleess Environment variables with the "SMF_" prefix are reserved and may be overwritten. ssvvcc..ssttaarrttdd supplies the "SMF_" environment variables specified in ssmmff__mmeetthhoodd(5) to the method. PATH is set to "//uussrr//ssbbiinn:://uussrr//bbiinn" by default. By default, all other environment variables supplied to ssvvcc..ssttaarrttdd are those inherited from iinniitt(1M). Duplicate entries are reduced to a single entry. The value used is undefined. Environment entries that are not prefixed with "<_n_a_m_e>=" are ignored. RReessttaarrtteerr OOppttiioonnss ssvvcc..ssttaarrttdd is not configured by command line options. Instead, configuration is read from the service configuration repository. You can use ssvvccccffgg(1M) to set all options and properties. The following configuration variables in the ooppttiioonnss property group are available to developers and administrators: bboooott__mmeessssaaggeess An _a_s_t_r_i_n_g (as defined in ssccff__vvaalluuee__iiss__ttyyppee; see ssccff__vvaalluuee__iiss__ttyyppee(3SCF)) that describes the default level of messages to print to the console during boot. The supported message options include qquuiieett and vveerrbboossee. The qquuiieett option prints minimal messages to console during boot. The vveerrbboossee option prints a single message per service started to indicate success or failure. You can use the bboooott --mm option to override the bboooott__mmeessssaaggeess setting at boot time. See kkeerrnneell(1M). llooggggiinngg Control the level of global service logging for ssvvcc..ssttaarrttdd. An _a_s_t_r_i_n_g (as defined in ssccff__vvaalluuee__iiss__ttyyppee; see ssccff__vvaalluuee__iiss__ttyyppee(3SCF)) that describes the default level of messages to log to ssyysslloogg (see ssyysslloogg(3C) and ssvvcc..ssttaarrttdd's global logfile, //vvaarr//ssvvcc//lloogg//ssvvcc..ssttaarrttdd..lloogg. The supported message options include qquuiieett, vveerrbboossee, and ddeebbuugg. The qquuiieett option sends error messages requiring administrative intervention to the console, ssyysslloogg and ssvvcc..ssttaarrttdd's global logfile. The vveerrbboossee option sends error messages requiring administrative intervention to the console, ssyysslloogg and ssvvcc..ssttaarrttdd's global logfile, and information about errors which do not require administrative intervention to ssvvcc..ssttaarrttdd's global logfile. A single message per service started is also sent to the console. The ddeebbuugg option sends ssvvcc..ssttaarrttdd debug messages to ssvvcc..ssttaarrttdd's global logfile, error messages requiring administrative intervention to the console, ssyysslloogg and ssvvcc..ssttaarrttdd's global logfile, and a single message per service started to the console. mmiilleessttoonnee An FMRI which determines the milestone used as the default boot level. Acceptable options include only the major milestones: svc:/milestone/single-user:default svc:/milestone/multi-user:default svc:/milestone/multi-user-server:default or the special values aallll or nnoonnee. aallll represents an idealized milestone that depends on every service. nnoonnee is a special milestone where no services are running apart from the master ssvvcc:://ssyysstteemm//ssvvcc//rreessttaarrtteerr::ddeeffaauulltt. By default, ssvvcc..ssttaarrttdd uses aallll, a synthetic milestone that depends on every service. If this property is specified, it overrides any iinniittddeeffaauulltt setting in iinniittttaabb(4). ssyysstteemm//rreeccoonnffiigguurree Indicates that a reconfiguration reboot has been requested. Services with actions that must key off of a reconfiguration reboot may check that this property exists and is set to 1 to confirm a reconfiguration boot has been requested. This property is managed by ssvvcc..ssttaarrttdd and should not be modified by the administrator. Configuration errors, such as disabling ssvvcc..ssttaarrttdd are logged by ssyysslloogg, but ignored. SSEERRVVIICCEE SSTTAATTEESS Services managed by ssvvcc..ssttaarrttdd can appear in any of the states described in ssmmff(5). The state definitions are unmodified by this restarter. SSEERRVVIICCEE RREEPPOORRTTIINNGG In addition to any logging done by the managed service, ssvvcc..ssttaarrttdd provides a common set of service reporting and logging mechanisms. Reporting properties ssvvcc..ssttaarrttdd updates a common set of properties on all services it manages. These properties are a common interface that can be used to take action based on service instance health. The ssvvccss(1) command can be used to easily display these properties. rreessttaarrtteerr//ssttaattee rreessttaarrtteerr//nneexxtt__ssttaattee The current and next (if currently in transition) state for an instance. rreessttaarrtteerr//aauuxxiilliiaarryy__ssttaattee A caption detailing additional information about the current instance state. The auxiliary state available for services managed by ssvvcc..ssttaarrttdd is: mmaaiinntteennaannccee fault_threshold_reached stop_method_failed administrative_request rreessttaarrtteerr//ssttaattee__ttiimmeessttaammpp The time when the current state was reached. rreessttaarrtteerr//ccoonnttrraacctt The primary process contract ID, if any, that under which the service instance is executing. LLooggss By default, ssvvcc..ssttaarrttdd provides logging of significant restarter actions for the service as well as method standard output and standard error file descriptors to //vvaarr//ssvvcc//lloogg//_s_e_r_v_i_c_e:_i_n_s_t_a_n_c_e.log. The level of logging to system global locations like //vvaarr//ssvvcc//lloogg//ssvvcc..ssttaarrttdd..lloogg and ssyysslloogg is controlled by the ooppttiioonnss//llooggggiinngg property. SSEERRVVIICCEE DDEEFFIINNIITTIIOONN When developing or configuring a service managed by ssvvcc..ssttaarrttdd, a common set of properties are used to affect the interaction between the service instance and the restarter. MMeetthhooddss The general form of methods for the fork/exec model provided by ssvvcc..ssttaarrttdd are presented in ssmmff__mmeetthhoodd(5). The following methods are supported as required or optional by services managed by ssvvcc..ssttaarrttdd. rreeffrreesshh Reload any appropriate configuration parameters from the repository or ccoonnffiigg file, without interrupting service. This is often implemented using SSIIGGHHUUPP for system daemons. If the service is unable to recognize configuration changes without a restart, no refresh method is provided. This method is optional. ssttaarrtt Start the service. Return success only after the application is available to consumers. Fail if a conflicting instance is already running, or if the service is unable to start. This method is required. ssttoopp Stop the service. In some cases, the stop method can be invoked when some or all of the service has already been stopped. Only return an error if the service is not entirely stopped on method return. This method is required. If the service does not need to take any action in a required method, it must specify the ::ttrruuee token for that method. ssvvcc..ssttaarrttdd honors any method context specified for the service or any specific method. The method expansion tokens described in ssmmff__mmeetthhoodd(5) are available for use in all methods invoked by ssvvcc..ssttaarrttdd. PPrrooppeerrttiieess An overview of the general properties is available in ssmmff(5). The specific way in which these general properties interacts with ssvvcc..ssttaarrttdd follows: ggeenneerraall//eennaabblleedd If enabled is set to true, the restarter attempts to start the service once all its dependencies are satisfied. If set to false, the service remains in the disabled state, not running. ggeenneerraall//rreessttaarrtteerr If this FMRI property is empty or set to ssvvcc:://ssyysstteemm//ssvvcc//rreessttaarrtteerr::ddeeffaauulltt, the service is managed by ssvvcc..ssttaarrttdd. Otherwise, the restarter specified is responsible (once it is available) for managing the service. ggeenneerraall//ssiinnggllee__iinnssttaannccee This was originally supposed to ensure that only one service instance could be in online or degraded state at once; however, it was never implemented, and is often incorrectly specified in multi- instance manifests. As such, it should be considered obsolete and not specified in new manifests. Additionally, ssvvcc..ssttaarrttdd managed services can define the optional properties listed below in the ssttaarrttdd property group. ssttaarrttdd//ccrriittiiccaall__ffaaiilluurree__ccoouunntt ssttaarrttdd//ccrriittiiccaall__ffaaiilluurree__ppeerriioodd The ccrriittiiccaall__ffaaiilluurree__ccoouunntt and ccrriittiiccaall__ffaaiilluurree__ppeerriioodd properties together specify the maximum number of service failures allowed in a given time interval before ssvvcc..ssttaarrttdd transitions the service to maintenance. If the number of failures exceeds ccrriittiiccaall__ffaaiilluurree__ccoouunntt in any period of ccrriittiiccaall__ffaaiilluurree__ppeerriioodd seconds, ssvvcc..ssttaarrttdd will transition the service to maintenance. ssttaarrttdd//dduurraattiioonn The dduurraattiioonn property defines the service's model. It can be set to ttrraannssiieenntt, cchhiilldd also known as "wwaaiitt" model services, or ccoonnttrraacctt (the default). ssttaarrttdd//iiggnnoorree__eerrrroorr The iiggnnoorree__eerrrroorr property, if set, specifies a comma-separated list of ignored events. Legitimate string values in that list are ccoorree and ssiiggnnaall. The default is to restart on all errors. ssttaarrttdd//nneeeedd__sseessssiioonn The nneeeedd__sseessssiioonn property, if set to true, indicates that the instance should be launched in its own session. The default is not to do so. ssttaarrttdd//uuttmmppxx__pprreeffiixx The uuttmmppxx__pprreeffiixx string property defines that the instance requires a valid uuttmmppxx entry prior to start method execution. The default is not to create a uuttmmppxx entry. SSEERRVVIICCEE FFAAIILLUURREE ssvvcc..ssttaarrttdd assumes that a method has failed if it returns a non-zero exit code or if fails to complete before the timeout specified expires. If $$SSMMFF__EEXXIITT__EERRRR__CCOONNFFIIGG or $$SSMMFF__EEXXIITT__EERRRR__FFAATTAALL is returned, ssvvcc..ssttaarrttdd immediately places the service in the maintenance state. For all other failures, ssvvcc..ssttaarrttdd places the service in the offline state. If a service is offline and its dependencies are satisfied, ssvvcc..ssttaarrttdd tries again to start the service (see ssmmff(5)). If a contract or transient service does not return from its start method before its defined timeout elapses, ssvvcc..ssttaarrttdd sends a SSIIGGKKIILLLL to the method, and returns the service to the offline state. If three failures happen in a row, or if the service is restarting more than once a second, ssvvcc..ssttaarrttdd places the service in the maintenance state. The conditions of service failure are defined by a combination of the service model (defined by the ssttaarrttdd//dduurraattiioonn property) and the value of the ssttaarrttdd//iiggnnoorree__eerrrroorr property. A contract model service fails if any of the following conditions occur: o all processes in the service exit o any processes in the service produce a core dump o a process outside the service sends a service process a fatal signal (for example, an administrator terminates a service process with the ppkkiillll command) The last two conditions may be ignored by the service by specifying core and/or signal in ssttaarrttdd//iiggnnoorree__eerrrroorr. Defining a service as transient means that ssvvcc..ssttaarrttdd does not track processes for that service. Thus, the potential faults described for contract model services are not considered failures for transient services. A transient service only enters the maintenance state if one of the method failure conditions occurs. "WWaaiitt" model services are restarted whenever the child process associated with the service exits. A child process that exits is not considered an error for "wwaaiitt" model services, and repeated failures do not lead to a transition to maintenance state. However, a wait service which is repeatedly exiting with an error that exceeds the default rate (5 failures/second) will be throttled back so that the service only restarts once per second. LLEEGGAACCYY SSEERRVVIICCEESS ssvvcc..ssttaarrttdd continues to provide support for services invoked during the startup run level transitions. Each //eettcc//rrcc??..dd directory is processed after all managed services which constitute the equivalent run level milestone have transitioned to the online state. Standard iinniitt scripts placed in the //eettcc//rrcc??..dd directories are run in the order of their sequence numbers. The milestone to run-level mapping is: mmiilleessttoonnee//ssiinnggllee--uusseerr Single-user (SS) mmiilleessttoonnee//mmuullttii--uusseerr Multi-user (22) mmiilleessttoonnee//mmuullttii--uusseerr--sseerrvveerr Multi-user with network services (33) Additionally, ssvvcc..ssttaarrttdd gives these legacy services visibility in SMF by inserting an instance per script into the repository. These legacy instances are visible using standard SMF interfaces such as ssvvccss(1), always appear in the LLEEGGAACCYY--RRUUNN state, cannot be modified, and can not be specified as dependencies of other services. The initial start time of the legacy service is captured as a convenience for the administrator. FFIILLEESS //vvaarr//ssvvcc//lloogg Directory where ssvvcc..ssttaarrttdd stores log files. //eettcc//ssvvcc//vvoollaattiillee Directory where ssvvcc..ssttaarrttdd stores log files in early stages of boot, before //vvaarr is mounted read- write. EEXXAAMMPPLLEE EExxaammppllee 11 Turning on Verbose Logging To turn on verbose logging, type the following: # /usr/sbin/svccfg -s system/svc/restarter:default svc:/system/svc/restarter:default> addpg options application svc:/system/svc/restarter:default> setprop options/logging = \ astring: verbose svc:/system/svc/restarter:default> exit This request will take effect on the next restart of ssvvcc..ssttaarrttdd. SSEEEE AALLSSOO ssvvccss(1), ssvvccpprroopp(1), kkeerrnneell(1M), iinniitt(1M), ssvvccaaddmm(1M), ssvvccccffgg(1M), ssvvcc..ccoonnffiiggdd(1M), sseettssiidd(2), ssyysslloogg(3C), lliibbssccff(3LIB), ssccff__vvaalluuee__iiss__ttyyppee(3SCF), ccoonnttrraacctt(4), iinniitt..dd(4), pprroocceessss(4), iinniittttaabb(4), aattttrriibbuutteess(5), ssmmff(5), ssmmff__mmeetthhoodd(5) December 11, 2019 SVC.STARTD(1M)