Standards, Environments, and Macros smf(5)
NAME
smf - service management facility
DESCRIPTION
The Solaris service management facility defines a program-
ming model for providing persistently running applications
called services. The facility also provides the infrastruc-
ture in which to run services. A service 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 informa-
tion. All service and instance objects are contained in a
scope that represents a collection of configuration informa-
tion. The configuration of the local Solaris instance is
called the "localhost" scope, and is the only currently sup-
ported scope.
Each service instance is named with a fault management
resource identifier (FMRI) with the scheme svc:. For exam-
ple, the syslogd(1M) daemon started at system startup is the
default service instance named:
svc:/localhost/system/system-log:default
svc:/system/system-log:default
system/system-log:default
Many commands also allow FMRI abbreviations. See the svcs(1)
man page for one such example.
In the above example, 'default' is the name of the instance
and 'system/system-log' is the service name. Service names
can comprise multiple 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 ser-
vices can be enabled or disabled with the svcadm(1M) com-
mand.
The list of managed service instances on a system can be
displayed with the svcs(1) command.
SunOS 5.11 Last change: 13 May 2008 1
Standards, Environments, and Macros smf(5)
Dependencies
Service instances can have dependencies on a set of entities
which can include services and files. Dependencies govern
when the service is started and automatically stopped. When
the dependencies of an enabled service are not satisfied,
the service is kept in the offline state. When its dependen-
cies 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
grouping:
requireall Satisfied when all cited services are run-
ning (online or degraded), or when all indi-
cated files are present.
requireany Satisfied when one of the cited services is
running (online or degraded), or when at
least one of the indicated files is present.
optionalall Satisfied if the cited services are running
(online or degraded) or do not run without
administrative action (disabled, mainte-
nance, not present, or offline waiting for
dependencies which do not start without
administrative action).
excludeall 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
requireall, requireany, or optionalall dependency is
stopped or refreshed, the SMF considers why the service was
stopped and the restarton attribute of the dependency to
decide whether to stop the service.
restarton 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
SunOS 5.11 Last change: 13 May 2008 2
Standards, Environments, and Macros smf(5)
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 excludeall dependencies, the
service is stopped if the cited service is started and the
restarton attribute is not none.
The dependencies on a service can be listed with svcs(1) or
svccfg(1M), and modified with svccfg(1M).
Restarters
Each service is managed by a restarter. The master restar-
ter, svc.startd(1M) manages states for the entire set of
service instances and their dependencies. The master restar-
ter acts on behalf of its services and on delegated restar-
ters that can provide specific execution 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 confi-
guration used by all restarters is given in
smfrestarter(5).
Methods
Each service or service instance must define a set of
methods that start, stop, and, optionally, refresh the ser-
vice. See smfmethod(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 page.
The methods for a service can be listed and modified using
the svccfg(1M) command.
SunOS 5.11 Last change: 13 May 2008 3
Standards, Environments, and Macros smf(5)
States
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 contracts events. The follow-
ing states are defined:
UNINITIALIZED This is the initial state for all service
instances. Instances are moved to mainte-
nance, offline, or a disabled state upon
evaluation by svc.startd(1M) or the
appropriate restarter.
OFLINE The instance is enabled, but not yet run-
ning or available to run. If restarter exe-
cution 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 application-model
specific and is defined by the restarter
responsible for the service instance.
Online is the expected operating state for
a properly configured service with all
dependencies satisfied. Failures of the
instance can lead to a degraded or mainte-
nance 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 com-
parison to normal operation. Failures of
the instance can lead to the maintenance
state. Failures 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. Administrative action (through svcadm
clear) is required to move the instance out
SunOS 5.11 Last change: 13 May 2008 4
Standards, Environments, and Macros smf(5)
of the maintenance state. The maintenance
state might be a temporarily reached state
if an administrative operation is underway.
DISABLED The instance is disabled. Enabling the ser-
vice 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 manage-
ment 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 originating state.
Properties and Property Groups
The dependencies, methods, delegated restarter, and instance
state mentioned above are represented as properties or pro-
perty groups of the service or service instance. A service
or service instance has an arbitrary number of property
groups in which to store application data. Using property
groups in this way allows the configuration of the applica-
tion to derive the attributes that the repository provides
for all data in the facility. The application can also use
the appropriate subset of the servicebundle(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 com-
mands and the high-level interfaces of libscf(3LIB) search
for the same property group-property combination on the ser-
vice that contains that instance. This allows common confi-
guration among service instances to be shared. Composition
can be viewed as an inheritance relationship between the
service instance and its parent service.
Properties are protected from modification by unauthorized
processes. See smfsecurity(5).
General Property Group
SunOS 5.11 Last change: 13 May 2008 5
Standards, Environments, and Macros smf(5)
The general property group applies to all service instances.
It includes the following properties:
enabled (boolean) Specifies whether the instance is
enabled. If this property is not
present on an instance, SMF does not
tell the instance's restarter about the
existence of the restarter.
restarter (fmri) The restarter for this service. See the
Restarters section for more informa-
tion. If this property is unset, the
default system restarter is used.
Snapshots
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 following set of snapshot types
might be available:
initial Initial configuration of the instance created
by the administrator or produced during pack-
age installation.
lastimport Configuration as prescribed by the manifest
of the service that is taken during
svccfg(1M) import operation. This snapshot
provides a baseline for determining property
customization.
previous Current configuration captured when an admin-
istrative 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
SunOS 5.11 Last change: 13 May 2008 6
Standards, Environments, and Macros smf(5)
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.
Configuration Repository
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 transactional and able to provide previ-
ous versions of properties and property groups associated
with each service or service instance.
The repository for service management facility data is
managed by svc.configd(1M).
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 pur-
poses. Service bundles are classified as one of the follow-
ing types:
manifests Files that contain the complete set of proper-
ties associated with a specific set of services
or service instances.
profiles Files that contain a set of service instances
and values for the enabled property (type
boolean in the general property group) on each
instance.
Service bundles can be imported or exported from a reposi-
tory using the svccfg(1M) command. See servicebundle(4) for
a description of the service bundle file format with guide-
lines for authoring service bundles.
A service archive is an XML file that contains the descrip-
tion and persistent properties of every service in the repo-
sitory, excluding transient properties such as service
state. This service archive is basically a 'svccfg export'
for every service which is not limited to named services.
Milestones
SunOS 5.11 Last change: 13 May 2008 7
Standards, Environments, and Macros smf(5)
An smf milestone is a service that aggregates a multiple
service dependencies. Usually, a milestone does nothing use-
ful itself, but declares a specific state of system-
readiness on which other services can depend. One example is
the name-services milestone, which simply depends upon the
currently enabled name services.
Legacy Startup Scripts
Startup programs in the /etc/rc?.d directories are executed
as part of the corresponding run-level milestone:
/etc/rcS.d milestone/single-user:default
/etc/rc2.d milestone/multi-user:default
/etc/rc3.d milestone/multi-user-server:default
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 (type
boolean in the general property group) and, generally, can-
not be manipulated with the svcadm(1M) command. No error
diagnosis or restart is done for these programs.
SEE ALSO
svcs(1), inetd(1M), svcadm(1M), svccfg(1M), svc.configd(1M),
svc.startd(1M), exec(2), fork(2), libscf(3LIB),
strftime(3C), contract(4), servicebundle(4),
smfbootstrap(5), smfmethod(5), smfrestarter(5),
smfsecurity(5)
SunOS 5.11 Last change: 13 May 2008 8
|
