1smf(5) Standards, Environments, and Macros smf(5)
2
6 smf - service management facility
7
9 The Solaris service management facility defines a programming model for
10 providing persistently running applications called services. The facil‐
11 ity also provides the infrastructure in which to run services. A ser‐
12 vice can represent a running application, the software state of a
13 device, or a set of other services. Services are represented in the
14 framework by service instance objects, which are children of service
15 objects. Instance objects can inherit or override the configuration of
16 the parent service object, which allows multiple service instances to
17 share configuration information. All service and instance objects are
18 contained in a scope that represents a collection of configuration
19 information. The configuration of the local Solaris instance is called
20 the "localhost" scope, and is the only currently supported scope.
21 Each service instance is named with a fault management resource identi‐
24 fier (FMRI) with the scheme svc:. For example, the syslogd(1M) daemon
25 started at system startup is the default service instance named:
26 svc://localhost/system/system-log:default
28 svc:/system/system-log:default
29 system/system-log:default
30 Many commands also allow FMRI abbreviations. See the svcs(1) man page
34 for one such example.
35 In the above example, 'default' is the name of the instance and 'sys‐
38 tem/system-log' is the service name. Service names can comprise multi‐
39 ple components separated by slashes (/). All components, except the
40 last, compose the category of the service. Site-specific services
41 should be named with a category beginning with 'site'.
42 A service instance is either enabled or disabled. All services can be
45 enabled or disabled with the svcadm(1M) command.
46 The list of managed service instances on a system can be displayed with
49 the svcs(1) command.
50 Dependencies
52 Service instances can have dependencies on a set of entities which can
53 include services and files. Dependencies govern when the service is
54 started and automatically stopped. When the dependencies of an enabled
55 service are not satisfied, the service is kept in the offline state.
56 When its dependencies are satisfied, the service is started. If the
57 start is successful, the service is transitioned to the online state.
58 Whether a dependency is satisfied is determined by its grouping:
61 require_all Satisfied when all cited services are running (online
63 or degraded), or when all indicated files are present.
64 require_any Satisfied when one of the cited services is running
67 (online or degraded), or when at least one of the indi‐
68 cated files is present.
69 optional_all Satisfied if the cited services are running (online or
72 degraded) or do not run without administrative action
73 (disabled, maintenance, not present, or offline waiting
74 for dependencies which do not start without administra‐
75 tive action).
76 exclude_all Satisfied when all of the cited services are disabled,
79 in the maintenance state, or when cited services or
80 files are not present.
81 Once running (online or degraded), if a service cited by a require_all,
85 require_any, or optional_all dependency is stopped or refreshed, the
86 SMF considers why the service was stopped and the restart_on attribute
87 of the dependency to decide whether to stop the service.
88 | restart_on value
90 event | none error restart refresh
91 -------------------+------------------------------
92 stop due to error | no yes yes yes
93 non-error stop | no no yes yes
94 refresh | no no no yes
95 A service is considered to have stopped due to an error if the service
99 has encountered a hardware error or a software error such as a core
100 dump. For exclude_all dependencies, the service is stopped if the cited
101 service is started and the restart_on attribute is not none.
102 The dependencies on a service can be listed with svcs(1) or svccfg(1M),
105 and modified with svccfg(1M).
106 Restarters
108 Each service is managed by a restarter. The master restarter,
109 svc.startd(1M) manages states for the entire set of service instances
110 and their dependencies. The master restarter acts on behalf of its ser‐
111 vices and on delegated restarters that can provide specific execution
112 environments for certain application classes. For instance, inetd(1M)
113 is a delegated restarter that provides its service instances with an
114 initial environment composed of a network connection as input and out‐
115 put file descriptors. Each instance delegated to inetd(1M) is in the
116 online state. While the daemon of a particular instance might not be
117 running, the instance is available to run.
118 As dependencies are satisfied when instances move to the online state,
121 svc.startd(1M) invokes start methods of other instances or directs the
122 delegated restarter to do so. These operations might overlap.
123 The current set of services and associated restarters can be examined
126 using svcs(1). A description of the common configuration used by all
127 restarters is given in smf_restarter(5).
128 Methods
130 Each service or service instance must define a set of methods that
131 start, stop, and, optionally, refresh the service. See smf_method(5)
132 for a more complete description of the method conventions for
133 svc.startd(1M) and similar fork(2)-exec(2) restarters.
134 Administrative methods, such as for the capture of legacy configuration
137 information into the repository, are discussed on the svccfg(1M) manual
138 page.
139 The methods for a service can be listed and modified using the svc‐
142 cfg(1M) command.
143 States
145 Each service instance is always in a well-defined state based on its
146 dependencies, the results of the execution of its methods, and its
147 potential contracts events. The following states are defined:
148 UNINITIALIZED This is the initial state for all service instances.
150 Instances are moved to maintenance, offline, or a dis‐
151 abled state upon evaluation by svc.startd(1M) or the
152 appropriate restarter.
153 OFFLINE The instance is enabled, but not yet running or avail‐
156 able to run. If restarter execution of the service
157 start method or the equivalent method is successful,
158 the instance moves to the online state. Failures might
159 lead to a degraded or maintenance state. Administra‐
160 tive action can lead to the uninitialized state.
161 ONLINE The instance is enabled and running or is available to
164 run. The specific nature of the online state is appli‐
165 cation-model specific and is defined by the restarter
166 responsible for the service instance. Online is the
167 expected operating state for a properly configured
168 service with all dependencies satisfied. Failures of
169 the instance can lead to a degraded or maintenance
170 state. Failures of services on which the instance
171 depends can lead to offline or degraded states.
172 DEGRADED The instance is enabled and running or available to
175 run. The instance, however, is functioning at a lim‐
176 ited capacity in comparison to normal operation. Fail‐
177 ures of the instance can lead to the maintenance
178 state. Failures of services on which the instance
179 depends can lead to offline or degraded states.
180 Restoration of capacity should result in a transition
181 to the online state.
182 MAINTENANCE The instance is enabled, but not able to run. Adminis‐
185 trative action (through svcadm clear) is required to
186 move the instance out of the maintenance state. The
187 maintenance state might be a temporarily reached state
188 if an administrative operation is underway.
189 DISABLED The instance is disabled. Enabling the service results
192 in a transition to the offline state and eventually to
193 the online state with all dependencies satisfied.
194 LEGACY-RUN This state represents a legacy instance that is not
197 managed by the service management facility. Instances
198 in this state have been started at some point, but
199 might or might not be running. Instances can only be
200 observed using the facility and are not transferred
201 into other states.
202 States can also have transitions that result in a return to the origi‐
206 nating state.
207 Properties and Property Groups
209 The dependencies, methods, delegated restarter, and instance state men‐
210 tioned above are represented as properties or property groups of the
211 service or service instance. A service or service instance has an arbi‐
212 trary number of property groups in which to store application data.
213 Using property groups in this way allows the configuration of the
214 application to derive the attributes that the repository provides for
215 all data in the facility. The application can also use the appropriate
216 subset of the service_bundle(4) DTD to represent its configuration data
217 within the framework.
218 Property lookups are composed. If a property group-property combination
221 is not found on the service instance, most commands and the high-level
222 interfaces of libscf(3LIB) search for the same property group-property
223 combination on the service that contains that instance. This allows
224 common configuration among service instances to be shared. Composition
225 can be viewed as an inheritance relationship between the service
226 instance and its parent service.
227 Properties are protected from modification by unauthorized processes.
230 See smf_security(5).
231 General Property Group
233 The general property group applies to all service instances. It
234 includes the following properties:
235 enabled (boolean) Specifies whether the instance is enabled. If this
237 property is not present on an instance, SMF does
238 not tell the instance's restarter about the exis‐
239 tence of the restarter.
240 restarter (fmri) The restarter for this service. See the Restarters
243 section for more information. If this property is
244 unset, the default system restarter is used.
245 Snapshots
248 Historical data about each instance in the repository is maintained by
249 the service management facility. This data is made available as read-
250 only snapshots for administrative inspection and rollback. The follow‐
251 ing set of snapshot types might be available:
252 initial Initial configuration of the instance created by the
254 administrator or produced during package installation.
255 last_import Configuration as prescribed by the manifest of the ser‐
258 vice that is taken during svccfg(1M) import operation.
259 This snapshot provides a baseline for determining prop‐
260 erty customization.
261 previous Current configuration captured when an administrative
264 undo operation is performed.
265 running The running configuration of the instance.
268 start Configuration captured during a successful transition to
271 the online state.
272 The svccfg(1M) command can be used to interact with snapshots.
276 Special Property Groups
278 Some property groups are marked as "non-persistent". These groups are
279 not backed up in snapshots and their content is cleared during system
280 boot. Such groups generally hold an active program state which does not
281 need to survive system restart.
282 Configuration Repository
284 The current state of each service instance, as well as the properties
285 associated with services and service instances, is stored in a system
286 repository managed by svc.configd(1M). This repository is transactional
287 and able to provide previous versions of properties and property groups
288 associated with each service or service instance.
289 The repository for service management facility data is managed by
292 svc.configd(1M).
293 Service Bundles, Manifests, and Profiles
295 The information associated with a service or service instance that is
296 stored in the configuration repository can be exported as XML-based
297 files. Such XML files, known as service bundles, are portable and suit‐
298 able for backup purposes. Service bundles are classified as one of the
299 following types:
300 manifests Files that contain the complete set of properties associ‐
302 ated with a specific set of services or service instances.
303 profiles Files that contain a set of service instances and values
306 for the enabled property (type boolean in the general
307 property group) on each instance.
308 Profiles can also contain configuration values for proper‐
310 ties in services and instances. Template elements cannot
311 be defined in a profile.
312 Service bundles can be imported or exported from a repository using the
316 svccfg(1M) command. See service_bundle(4) for a description of the ser‐
317 vice bundle file format with guidelines for authoring service bundles.
318 A service archive is an XML file that contains the description and per‐
321 sistent properties of every service in the repository, excluding tran‐
322 sient properties such as service state. This service archive is basi‐
323 cally a 'svccfg export' for every service which is not limited to named
324 services.
325 Milestones
327 An smf milestone is a service that aggregates a multiple service depen‐
328 dencies. Usually, a milestone does nothing useful itself, but declares
329 a specific state of system-readiness on which other services can
330 depend. One example is the name-services milestone, which simply
331 depends upon the currently enabled name services.
332 Legacy Startup Scripts
334 Startup programs in the /etc/rc?.d directories are executed as part of
335 the corresponding run-level milestone:
336 /etc/rcS.d milestone/single-user:default
338 /etc/rc2.d milestone/multi-user:default
341 /etc/rc3.d milestone/multi-user-server:default
344 Execution of each program is represented as a reduced-functionality
348 service instance named by the program's path. These instances are held
349 in a special legacy-run state.
350 These instances do not have an enabled property (type boolean in the
353 general property group) and, generally, cannot be manipulated with the
354 svcadm(1M) command. No error diagnosis or restart is done for these
355 programs.
356
358 svcs(1), inetd(1M), svcadm(1M), svccfg(1M), svc.configd(1M),
359 svc.startd(1M), exec(2), fork(2), libscf(3LIB), strftime(3C), con‐
360 tract(4), service_bundle(4), smf_bootstrap(5), smf_method(5),
361 smf_restarter(5), smf_security(5)
362SunOS 5.11 6 Jul 2009 smf(5)