SVC.STARTD(8) Maintenance Commands and Procedures SVC.STARTD(8)
NAME
svc.startd - Service Management Facility master restarter
SYNOPSIS
/lib/svc/bin/svc.startd svc:/system/svc/restarter:defaultDESCRIPTION
svc.startd is the master restarter daemon for Service Management Facility
(SMF) and the default restarter for all services.
svc.startd starts,
stops, and restarts services based on administrative requests, system
failures, or application failures.
svc.startd maintains service state, as well as being responsible for
managing faults in accordance with the dependencies of each service.
svc.startd is invoked automatically during system startup. It is
restarted if any failures occur.
svc.startd should never be invoked
directly.
See
smf_restarter(7) for information on configuration and behavior common
to all restarters.
svcs(1) reports status for all services managed by the Service
Configuration Facility.
svcadm(8) allows manipulation of service
instances with respect to the service's restarter.
Environment Variables
Environment variables with the "SMF_" prefix are reserved and may be
overwritten.
svc.startd supplies the "SMF_" environment variables specified in
smf_method(7) to the method. PATH is set to "
/usr/sbin:/usr/bin" by
default. By default, all other environment variables supplied to
svc.startd are those inherited from
init(8).
Duplicate entries are reduced to a single entry. The value used is
undefined. Environment entries that are not prefixed with "<
name>=" are
ignored.
Restarter Options
svc.startd is not configured by command line options. Instead,
configuration is read from the service configuration repository. You can
use
svccfg(8) to set all options and properties.
The following configuration variables in the
options property group are
available to developers and administrators:
boot_messages An
astring (as defined in
scf_value_is_type; see
scf_value_is_type(3SCF)) that describes the default level of messages
to print to the console during boot. The supported message options
include
quiet and
verbose. The
quiet option prints minimal messages
to console during boot. The
verbose option prints a single message
per service started to indicate success or failure. You can use the
boot -m option to override the
boot_messages setting at boot time.
See
kernel(8).
logging Control the level of global service logging for
svc.startd. An
astring (as defined in
scf_value_is_type; see
scf_value_is_type(3SCF)) that describes the default level of messages
to log to
syslog (see
syslog(3C) and
svc.startd's global logfile,
/var/svc/log/svc.startd.log. The supported message options include
quiet,
verbose, and
debug. The
quiet option sends error messages
requiring administrative intervention to the console,
syslog and
svc.startd's global logfile. The
verbose option sends error messages
requiring administrative intervention to the console,
syslog and
svc.startd's global logfile, and information about errors which do
not require administrative intervention to
svc.startd's global
logfile. A single message per service started is also sent to the
console. The
debug option sends
svc.startd debug messages to
svc.startd's global logfile, error messages requiring administrative
intervention to the console,
syslog and
svc.startd's global logfile,
and a single message per service started to the console.
milestone 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
all or
none.
all represents an idealized
milestone that depends on every service.
none is a special milestone
where no services are running apart from the master
svc:/system/svc/restarter:default. By default,
svc.startd uses
all, a
synthetic milestone that depends on every service. If this property
is specified, it overrides any
initdefault setting in
inittab(5).
system/reconfigure 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
svc.startd and should not be modified by
the administrator.
Configuration errors, such as disabling
svc.startd are logged by
syslog,
but ignored.
SERVICE STATES
Services managed by
svc.startd can appear in any of the states described
in
smf(7). The state definitions are unmodified by this restarter.
SERVICE REPORTING
In addition to any logging done by the managed service,
svc.startd provides a common set of service reporting and logging mechanisms.
Reporting properties
svc.startd 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
svcs(1) command
can be used to easily display these properties.
restarter/state restarter/next_state The current and next (if currently in transition) state for an
instance.
restarter/auxiliary_state A caption detailing additional information about the current instance
state. The auxiliary state available for services managed by
svc.startd is:
maintenance fault_threshold_reached
stop_method_failed
administrative_request
restarter/state_timestamp The time when the current state was reached.
restarter/contract The primary process contract ID, if any, that under which the service
instance is executing.
Logs By default,
svc.startd provides logging of significant restarter actions
for the service as well as method standard output and standard error file
descriptors to
/var/svc/log/service:
instance.log. The level of logging to
system global locations like
/var/svc/log/svc.startd.log and
syslog is
controlled by the
options/logging property.
SERVICE DEFINITION
When developing or configuring a service managed by
svc.startd, a common
set of properties are used to affect the interaction between the service
instance and the restarter.
Methods The general form of methods for the fork/exec model provided by
svc.startd are presented in
smf_method(7). The following methods are
supported as required or optional by services managed by
svc.startd.
refresh Reload any appropriate configuration parameters from the
repository or
config file, without interrupting service. This
is often implemented using
SIGHUP for system daemons. If the
service is unable to recognize configuration changes without a
restart, no refresh method is provided.
This method is optional.
start 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.
stop 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
:true token for that method.
svc.startd honors any method context specified for the service or any
specific method. The method expansion tokens described in
smf_method(7) are available for use in all methods invoked by
svc.startd.
Properties An overview of the general properties is available in
smf(7). The
specific way in which these general properties interacts with
svc.startd follows:
general/enabled 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.
general/restarter If this FMRI property is empty or set to
svc:/system/svc/restarter:default, the service is managed by
svc.startd. Otherwise, the restarter specified is responsible (once
it is available) for managing the service.
general/single_instance 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,
svc.startd managed services can define the optional
properties listed below in the
startd property group.
startd/critical_failure_count startd/critical_failure_period The
critical_failure_count and
critical_failure_period properties
together specify the maximum number of service failures allowed in a
given number of seconds before
svc.startd transitions the service to
maintenance. If the number of failures exceeds
critical_failure_count in any period of
critical_failure_period seconds,
svc.startd will transition the service to maintenance. The
critical_failure_count value is limited to the range 1-10 and
defaults to 10. The
critical_failure_period defaults to 600 seconds.
startd/duration The
duration property defines the service's model. It can be set to
transient,
child also known as "
wait" model services, or
contract (the default).
startd/ignore_error The
ignore_error property, if set, specifies a comma-separated list
of ignored events. Legitimate string values in that list are
core and
signal. The default is to restart on all errors.
startd/need_session The
need_session property, if set to true, indicates that the
instance should be launched in its own session. The default is not to
do so.
startd/utmpx_prefix The
utmpx_prefix string property defines that the instance requires a
valid
utmpx entry prior to start method execution. The default is not
to create a
utmpx entry.
SERVICE FAILURE
svc.startd 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
$SMF_EXIT_ERR_CONFIG or
$SMF_EXIT_ERR_FATAL is returned,
svc.startd immediately places the service in the maintenance state. For all other
failures,
svc.startd places the service in the offline state. If a
service is offline and its dependencies are satisfied,
svc.startd tries
again to start the service (see
smf(7)).
If a contract or transient service does not return from its start method
before its defined timeout elapses,
svc.startd sends a
SIGKILL 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,
svc.startd places the service in the maintenance
state.
The conditions of service failure are defined by a combination of the
service model (defined by the
startd/duration property) and the value of
the
startd/ignore_error 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
pkill command)
The last two conditions may be ignored by the service by specifying core
and/or signal in
startd/ignore_error.
Defining a service as transient means that
svc.startd 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.
"
Wait" model services are restarted whenever the child process associated
with the service exits. A child process that exits is not considered an
error for "
wait" 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.
LEGACY SERVICES
svc.startd continues to provide support for services invoked during the
startup run level transitions. Each
/etc/rc?.d directory is processed
after all managed services which constitute the equivalent run level
milestone have transitioned to the online state. Standard
init scripts
placed in the
/etc/rc?.d directories are run in the order of their
sequence numbers.
The milestone to run-level mapping is:
milestone/single-user Single-user (
S)
milestone/multi-user Multi-user (
2)
milestone/multi-user-server Multi-user with network services (
3)
Additionally,
svc.startd 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
svcs(1),
always appear in the
LEGACY-RUN 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.
FILES
/var/svc/log Directory where
svc.startd stores log files.
/etc/svc/volatile Directory where
svc.startd stores log files in early
stages of boot, before
/var is mounted read-write.
EXAMPLE
Example 1: 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
svc.startd.
SEE ALSO
svcprop(1),
svcs(1),
setsid(2),
syslog(3C),
libscf(3LIB),
scf_value_is_type(3SCF),
contract(5),
init.d(5),
inittab(5),
process(5),
attributes(7),
smf(7),
smf_method(7),
init(8),
kernel(8),
svc.configd(8),
svcadm(8),
svccfg(8) December 11, 2019
SVC.STARTD(8)