smf(5) Standards, Environments, and Macros smf(5)
smf - service management facility
The Solaris service management facility defines a programming model for
providing persistently running applications called services. The facil-
ity also provides the infrastructure in which to run services. A ser-
vice can represent a running application, the software state of a
device, or a set of other services. Services are represented in the
framework by service instance objects, which are children of service
objects. Instance objects can inherit or override the configuration of
the parent service object, which allows multiple service instances to
share configuration information. All service and instance objects are
contained in a scope that represents a collection of configuration
information. The configuration of the local Solaris instance is called
the "localhost" scope, and is the only currently supported scope.
Each service instance is named with a fault management resource identi-
fier (FMRI) with the scheme "svc:". For example, the syslogd(1M) daemon
started at system startup is the default service instance named:
In the above example, 'default' is the name of the instance and 'sys-
tem/system-log' is the service name. Service names may comprise multi-
ple components separated by slashes (/). All components, except the
last, compose the category of the service. Site-specific services
should be named with a category beginning with 'site'.
A service instance is either enabled or disabled. All services can be
enabled or disabled with the svcadm(1M) command.
The list of managed service instances on a system can be displayed with
the svcs(1) command.
Service instances may have dependencies on services or files. Those
dependencies govern when the service is started and automatically
stopped. When the dependencies of an enabled service are not satis-
fied, the service is kept in the offline state. When its dependencies
are satisfied, the service is started. If the start is successful, the
service is transitioned to the online state. Whether a dependency is
satisfied is determined by its type:
require_all Satisfied when all cited services are running (online
or degraded), or when all indicated files are present.
require_any Satisfied when one of the cited services is running
(online or degraded), or when at least one of the indi-
cated files is present.
optional_all Satisfied when all of the cited services are running
(online or degraded), disabled, in the maintenance
state, or when cited services are not present. For
files, this type is the same as require_all.
exclude_all Satisfied when all of the cited services are disabled,
in the maintenance state, or when cited services or
files are not present.
Once running (online or degraded), if a service cited by a require_all,
require_any, or optional_all dependency is stopped or refreshed, the
SMF considers why the service was stopped and the restart_on attribute
of the dependency to decide whether to stop the service.
| restart_on value
event | none error restart refresh
stop due to error | no yes yes yes
non-error stop | no no yes yes
refresh | no no no yes
A service is considered to have stopped due to an error if the service
has encountered a hardware error or a software error such as a core
dump. For exclude_all dependencies, the service is stopped if the
cited service is started and the restart_on attribute is not none.
The dependencies on a service can be listed with svcs(1) or svccfg(1M),
and modified with svccfg(1M).
Each service is managed by a restarter. The master restarter,
svc.startd(1M) manages states for the entire set of service instances
and their dependencies. The master restarter acts on behalf of its
services and on delegated restarters that can provide specific execu-
tion environments for certain application classes. For instance,
inetd(1M) is a delegated restarter that provides its service instances
with an initial environment composed of a network connection as input
and output file descriptors. Each instance delegated to inetd(1M) is
in the online state. While the daemon of a particular instance might
not be running, the instance is available to run.
As dependencies are satisfied when instances move to the online state,
svc.startd(1M) invokes start methods of other instances or directs the
delegated restarter to do so. These operations might overlap.
The current set of services and associated restarters can be examined
using svcs(1). A description of the common configuration used by all
restarters is given in smf_restarter(5).
Each service or service instance must define a set of methods that
start, stop, and, optionally, refresh the service. See smf_method(5)
for a more complete description of the method conventions for
svc.startd(1M) and similar fork(2)-exec(2) restarters.
Administrative methods, such as for the capture of legacy configuration
information into the repository, are discussed on the svccfg(1M) manual
The methods for a service can be listed and modified using the svc-
Each service instance is always in a well-defined state based on its
dependencies, the results of the execution of its methods, and its
potential receipt of events from the contracts filesystem. The follow-
ing states are defined:
UNINITIALIZED This is the initial state for all service instances.
Instances are moved to maintenance, offline, or a dis-
abled state upon evaluation by svc.startd(1M) or the
OFFLINE The instance is enabled, but not yet running or avail-
able to run. If restarter execution of the service
start method or the equivalent method is successful,
the instance moves to the online state. Failures might
lead to a degraded or maintenance state. Administrative
action can lead to the uninitialized state.
ONLINE The instance is enabled and running or is available to
run. The specific nature of the online state is appli-
cation-model specific and is defined by the restarter
responsible for the service instance. Online is the
expected operating state for a properly configured ser-
vice with all dependencies satisfied. Failures of the
instance can lead to a degraded or maintenance state.
Failures of services on which the instance depends can
lead to offline or degraded states.
DEGRADED The instance is enabled and running or available to
run. The instance, however, is functioning at a limited
capacity in comparison to normal operation. Failures of
the instance can lead to the maintenance state. Fail-
ures of services on which the instance depends can lead
to offline or degraded states. Restoration of capacity
should result in a transition to the online state.
MAINTENANCE The instance is enabled, but not able to run. Adminis-
trative action is required to restore the instance to
offline and subsequent states. The maintenance state
might be a temporarily reached state if an administra-
tive operation is underway.
DISABLED The instance is disabled. Enabling the service results
in a transition to the offline state and eventually to
the online state with all dependencies satisfied.
LEGACY-RUN This state represents a legacy instance that is not
managed by the service management facility. Instances
in this state have been started at some point, but
might or might not be running. Instances can only be
observed using the facility and are not transferred
into other states.
States can also have transitions that result in a return to the origi-
Properties and Property Groups
The dependencies, methods, delegated restarter, and instance state men-
tioned above are represented as properties or property groups of the
service or service instance. A service or service instance has an arbi-
trary number of property groups in which to store application data.
Using property groups in this way allows the configuration of the
application to derive the attributes that the repository provides for
all data in the facility. The application can also use the appropriate
subset of the service_bundle(4) DTD to represent its configuration data
within the framework.
Property lookups are composed. If a property group-property combination
is not found on the service instance, most commands and the high-level
interfaces of libscf(3LIB) search for the same property group-property
combination on the service that contains that instance. This feature
allows common configuration among service instances to be shared. Com-
position can be viewed as an inheritance relationship between the ser-
vice instance and its parent service.
Properties are protected from modification by unauthorized processes.
Historical data about each instance in the repository is maintained by
the service management facility. This data is made available as read-
only snapshots for administrative inspection and rollback. The follow-
ing set of snapshot types might be available:
initial Initial configuration of the instance created by the
administrator or produced during package installation.
last_import Configuration as prescribed by the manifest of the ser-
vice that is taken during svccfg(1M) import operation.
This snapshot provides a baseline for determining prop-
previous Current configuration captured when an administrative
undo operation is performed.
running The running configuration of the instance.
start Configuration captured during a successful transition
to the online state.
The svccfg(1M) command can be used to interact with snapshots.
Special Property Groups
Some property groups are marked as "non-persistent". These groups are
not backed up in snapshots and their content is cleared during system
boot. Such groups generally hold an active program state which does not
need to survive system restart.
The current state of each service instance, as well as the properties
associated with services and service instances, is stored in a system
repository managed by svc.configd(1M). This repository is transac-
tional and able to provide previous versions of properties and property
groups associated with each service or service instance.
The repository for service management facility data is managed by
Service Bundles, Manifests, and Profiles
The information associated with a service or service instance that is
stored in the configuration repository can be exported as XML-based
files. Such XML files, known as service bundles, are portable and
suitable for backup purposes. Service bundles are classified as one of
the following types:
manifests Files that contain the complete set of properties asso-
ciated with a specific set of services or service
profiles Files that contain a set of service instances and val-
ues for the enabled property on each instance.
Service bundles can be imported or exported from a repository using the
svccfg(1M) command. See service_bundle(4) for a description of the ser-
vice bundle file format with guidelines for authoring service bundles.
A service archive is an XML file that contains the description and per-
sistent properties of every service in the repository, excluding tran-
sient properties such as service state. This service archive is basi-
cally a 'svccfg export' for every service which is not limited to named
Legacy Startup Scripts
Startup programs in the /etc/rc?.d directories are executed as part of
the corresponding run-level milestone:
Execution of each program is represented as a reduced-functionality
service instance named by the program's path. These instances are held
in a special legacy-run state.
These instances do not have an enabled property and, generally, cannot
be manipulated with the svcadm(1M) command. No error diagnosis or
restart is done for these programs.
svcs(1), inetd(1M), svcadm(1M), svccfg(1M), svc.configd(1M),
svc.startd(1M), exec(2), fork(2), libscf(3LIB), strftime(3C), con-
tract(4), service_bundle(4), user_attr(4), smf_method(5),
SunOS 5.10 2 Dec 2004 smf(5)