| blob | f26ff03ddfeb104de62616f34b065b334cdaf1b8 |
1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SMF 5 "Jul 6, 2009"
7 .SH NAME
8 smf \- service management facility
9 .SH DESCRIPTION
10 .sp
11 .LP
12 The Solaris service management facility defines a programming model for
13 providing persistently running applications called \fIservices\fR. The facility
14 also provides the infrastructure in which to run services. A service can
15 represent a running application, the software state of a device, or a set of
16 other services. Services are represented in the framework by \fIservice
17 instance\fR objects, which are children of service objects. Instance objects
18 can inherit or override the configuration of the parent service object, which
19 allows multiple service instances to share configuration information. All
20 service and instance objects are contained in a \fIscope\fR that represents a
21 collection of configuration information. The configuration of the local Solaris
22 instance is called the "localhost" scope, and is the only currently supported
23 scope.
24 .sp
25 .LP
26 Each service instance is named with a fault management resource identifier
27 (FMRI) with the scheme \fBsvc:\fR. For example, the \fBsyslogd\fR(1M) daemon
28 started at system startup is the default service instance named:
29 .sp
30 .in +2
31 .nf
32 svc://localhost/system/system-log:default
33 svc:/system/system-log:default
34 system/system-log:default
35 .fi
36 .in -2
38 .sp
39 .LP
40 Many commands also allow FMRI abbreviations. See the \fBsvcs\fR(1) man page for
41 one such example.
42 .sp
43 .LP
44 In the above example, 'default' is the name of the instance
45 and 'system/system-log' is the service name. Service names can comprise multiple
46 components separated by slashes (/). All components, except the last, compose
47 the \fIcategory\fR of the service. Site-specific services should be named with
48 a category beginning with 'site'.
49 .sp
50 .LP
51 A service instance is either enabled or disabled. All services can be enabled
52 or disabled with the \fBsvcadm\fR(1M) command.
53 .sp
54 .LP
55 The list of managed service instances on a system can be displayed with the
56 \fBsvcs\fR(1) command.
57 .SS "Dependencies"
58 .sp
59 .LP
60 Service instances can have dependencies on a set of \fBentities\fR which can
61 include services and files. Dependencies govern when the service is started and
62 automatically stopped. When the dependencies of an enabled service are not
63 satisfied, the service is kept in the offline state. When its dependencies are
64 satisfied, the service is started. If the start is successful, the service is
65 transitioned to the online state.
66 .sp
67 .LP
68 Whether a dependency is satisfied is determined by its \fBgrouping\fR:
69 .sp
70 .ne 2
71 .na
72 \fB\fBrequire_all\fR\fR
73 .ad
74 .RS 16n
75 Satisfied when all cited services are running (online or degraded), or when all
76 indicated files are present.
77 .RE
79 .sp
80 .ne 2
81 .na
82 \fB\fBrequire_any\fR\fR
83 .ad
84 .RS 16n
85 Satisfied when one of the cited services is running (online or degraded), or
86 when at least one of the indicated files is present.
87 .RE
89 .sp
90 .ne 2
91 .na
92 \fB\fBoptional_all\fR\fR
93 .ad
94 .RS 16n
95 Satisfied if the cited services are running (online or degraded) or do not run
96 without administrative action (disabled, maintenance, not present, or offline
97 waiting for dependencies which do not start without administrative action).
98 .RE
100 .sp
101 .ne 2
102 .na
103 \fB\fBexclude_all\fR\fR
104 .ad
105 .RS 16n
106 Satisfied when all of the cited services are disabled, in the maintenance
107 state, or when cited services or files are not present.
108 .RE
110 .sp
111 .LP
112 Once running (online or degraded), if a service cited by a \fBrequire_all\fR,
113 \fBrequire_any\fR, or \fBoptional_all\fR dependency is stopped or refreshed,
114 the SMF considers why the service was stopped and the \fBrestart_on\fR
115 attribute of the dependency to decide whether to stop the service.
116 .sp
117 .in +2
118 .nf
119 | restart_on value
120 event | none error restart refresh
121 -------------------+------------------------------
122 stop due to error | no yes yes yes
123 non-error stop | no no yes yes
124 refresh | no no no yes
125 .fi
126 .in -2
128 .sp
129 .LP
130 A service is considered to have stopped due to an error if the service has
131 encountered a hardware error or a software error such as a core dump. For
132 \fBexclude_all\fR dependencies, the service is stopped if the cited service is
133 started and the \fBrestart_on\fR attribute is not \fBnone\fR.
134 .sp
135 .LP
136 The dependencies on a service can be listed with \fBsvcs\fR(1)\ or
137 \fBsvccfg\fR(1M), and modified with \fBsvccfg\fR(1M).
138 .SS "Restarters"
139 .sp
140 .LP
141 Each service is managed by a restarter. The master restarter,
142 \fBsvc.startd\fR(1M) manages states for the entire set of service instances and
143 their dependencies. The master restarter acts on behalf of its services and on
144 delegated restarters that can provide specific execution environments for
145 certain application classes. For instance, \fBinetd\fR(1M) is a delegated
146 restarter that provides its service instances with an initial environment
147 composed of a network connection as input and output file descriptors. Each
148 instance delegated to \fBinetd\fR(1M) is in the online state. While the daemon
149 of a particular instance might not be running, the instance is available to
150 run.
151 .sp
152 .LP
153 As dependencies are satisfied when instances move to the online state,
154 \fBsvc.startd\fR(1M) invokes start methods of other instances or directs the
155 delegated restarter to do so. These operations might overlap.
156 .sp
157 .LP
158 The current set of services and associated restarters can be examined using
159 \fBsvcs\fR(1). A description of the common configuration used by all restarters
160 is given in \fBsmf_restarter\fR(5).
161 .SS "Methods"
162 .sp
163 .LP
164 Each service or service instance must define a set of methods that start, stop,
165 and, optionally, refresh the service. See \fBsmf_method\fR(5) for a more
166 complete description of the method conventions for \fBsvc.startd\fR(1M) and
167 similar \fBfork\fR(2)-\fBexec\fR(2) restarters.
168 .sp
169 .LP
170 Administrative methods, such as for the capture of legacy configuration
171 information into the repository, are discussed on the \fBsvccfg\fR(1M) manual
172 page.
173 .sp
174 .LP
175 The methods for a service can be listed and modified using the \fBsvccfg\fR(1M)
176 command.
177 .SS "States"
178 .sp
179 .LP
180 Each service instance is always in a well-defined state based on its
181 dependencies, the results of the execution of its methods, and its potential
182 contracts events. The following states are defined:
183 .sp
184 .ne 2
185 .na
186 \fB\fBUNINITIALIZED\fR\fR
187 .ad
188 .RS 17n
189 This is the initial state for all service instances. Instances are moved to
190 maintenance, offline, or a disabled state upon evaluation by
191 \fBsvc.startd\fR(1M) or the appropriate restarter.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fBOFFLINE\fR\fR
198 .ad
199 .RS 17n
200 The instance is enabled, but not yet running or available to run. If restarter
201 execution of the service start method or the equivalent method is successful,
202 the instance moves to the online state. Failures might lead to a degraded or
203 maintenance state. Administrative action can lead to the uninitialized state.
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fBONLINE\fR\fR
210 .ad
211 .RS 17n
212 The instance is enabled and running or is available to run. The specific nature
213 of the online state is application-model specific and is defined by the
214 restarter responsible for the service instance. Online is the expected
215 operating state for a properly configured service with all dependencies
216 satisfied. Failures of the instance can lead to a degraded or maintenance
217 state. Failures of services on which the instance depends can lead to offline
218 or degraded states.
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fBDEGRADED\fR\fR
225 .ad
226 .RS 17n
227 The instance is enabled and running or available to run. The instance, however,
228 is functioning at a limited capacity in comparison to normal operation.
229 Failures of the instance can lead to the maintenance state. Failures of
230 services on which the instance depends can lead to offline or degraded states.
231 Restoration of capacity should result in a transition to the online state.
232 .RE
234 .sp
235 .ne 2
236 .na
237 \fB\fBMAINTENANCE\fR\fR
238 .ad
239 .RS 17n
240 The instance is enabled, but not able to run. Administrative action (through
241 \fBsvcadm clear\fR) is required to move the instance out of the maintenance
242 state. The maintenance state might be a temporarily reached state if an
243 administrative operation is underway.
244 .RE
246 .sp
247 .ne 2
248 .na
249 \fB\fBDISABLED\fR\fR
250 .ad
251 .RS 17n
252 The instance is disabled. Enabling the service results in a transition to the
253 offline state and eventually to the online state with all dependencies
254 satisfied.
255 .RE
257 .sp
258 .ne 2
259 .na
260 \fB\fBLEGACY-RUN\fR\fR
261 .ad
262 .RS 17n
263 This state represents a legacy instance that is not managed by the service
264 management facility. Instances in this state have been started at some point,
265 but might or might not be running. Instances can only be observed using the
266 facility and are not transferred into other states.
267 .RE
269 .sp
270 .LP
271 States can also have transitions that result in a return to the originating
272 state.
273 .SS "Properties and Property Groups"
274 .sp
275 .LP
276 The dependencies, methods, delegated restarter, and instance state mentioned
277 above are represented as properties or property groups of the service or
278 service instance. A service or service instance has an arbitrary number of
279 property groups in which to store application data. Using property groups in
280 this way allows the configuration of the application to derive the attributes
281 that the repository provides for all data in the facility. The application can
282 also use the appropriate subset of the \fBservice_bundle\fR(4) DTD to represent
283 its configuration data within the framework.
284 .sp
285 .LP
286 Property lookups are composed. If a property group-property combination is not
287 found on the service instance, most commands and the high-level interfaces of
288 \fBlibscf\fR(3LIB) search for the same property group-property combination on
289 the service that contains that instance. This allows common configuration among
290 service instances to be shared. Composition can be viewed as an inheritance
291 relationship between the service instance and its parent service.
292 .sp
293 .LP
294 Properties are protected from modification by unauthorized processes. See
295 \fBsmf_security\fR(5).
296 .SS "General Property Group"
297 .sp
298 .LP
299 The \fBgeneral\fR property group applies to all service instances. It includes
300 the following properties:
301 .sp
302 .ne 2
303 .na
304 \fBenabled (boolean)\fR
305 .ad
306 .RS 21n
307 Specifies whether the instance is enabled. If this property is not present on
308 an instance, SMF does not tell the instance's restarter about the existence of
309 the restarter.
310 .RE
312 .sp
313 .ne 2
314 .na
315 \fBrestarter (fmri)\fR
316 .ad
317 .RS 21n
318 The restarter for this service. See the Restarters section for more
319 information. If this property is unset, the default system restarter is used.
320 .RE
322 .SS "Snapshots"
323 .sp
324 .LP
325 Historical data about each instance in the repository is maintained by the
326 service management facility. This data is made available as read-only snapshots
327 for administrative inspection and rollback. The following set of snapshot types
328 might be available:
329 .sp
330 .ne 2
331 .na
332 \fB\fBinitial\fR\fR
333 .ad
334 .RS 15n
335 Initial configuration of the instance created by the administrator or produced
336 during package installation.
337 .RE
339 .sp
340 .ne 2
341 .na
342 \fB\fBlast_import\fR\fR
343 .ad
344 .RS 15n
345 Configuration as prescribed by the manifest of the service that is taken during
346 \fBsvccfg\fR(1M) import operation. This snapshot provides a baseline for
347 determining property customization.
348 .RE
350 .sp
351 .ne 2
352 .na
353 \fB\fBprevious\fR\fR
354 .ad
355 .RS 15n
356 Current configuration captured when an administrative undo operation is
357 performed.
358 .RE
360 .sp
361 .ne 2
362 .na
363 \fB\fBrunning\fR\fR
364 .ad
365 .RS 15n
366 The running configuration of the instance.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fBstart\fR\fR
373 .ad
374 .RS 15n
375 Configuration captured during a successful transition to the online state.
376 .RE
378 .sp
379 .LP
380 The \fBsvccfg\fR(1M) command can be used to interact with snapshots.
381 .SS "Special Property Groups"
382 .sp
383 .LP
384 Some property groups are marked as "non-persistent". These groups are not
385 backed up in snapshots and their content is cleared during system boot. Such
386 groups generally hold an active program state which does not need to survive
387 system restart.
388 .SS "Configuration Repository"
389 .sp
390 .LP
391 The current state of each service instance, as well as the properties
392 associated with services and service instances, is stored in a system
393 repository managed by \fBsvc.configd\fR(1M). This repository is transactional
394 and able to provide previous versions of properties and property groups
395 associated with each service or service instance.
396 .sp
397 .LP
398 The repository for service management facility data is managed by
399 \fBsvc.configd\fR(1M).
400 .SS "Service Bundles, Manifests, and Profiles"
401 .sp
402 .LP
403 The information associated with a service or service instance that is stored in
404 the configuration repository can be exported as XML-based files. Such XML
405 files, known as service bundles, are portable and suitable for backup purposes.
406 Service bundles are classified as one of the following types:
407 .sp
408 .ne 2
409 .na
410 \fB\fBmanifests\fR\fR
411 .ad
412 .RS 13n
413 Files that contain the complete set of properties associated with a specific
414 set of services or service instances.
415 .RE
417 .sp
418 .ne 2
419 .na
420 \fB\fBprofiles\fR\fR
421 .ad
422 .RS 13n
423 Files that contain a set of service instances and values for the enabled
424 property (type \fBboolean\fR in the general property group) on each instance.
425 .sp
426 Profiles can also contain configuration values for properties in services and
427 instances. Template elements cannot be defined in a profile.
428 .RE
430 .sp
431 .LP
432 Service bundles can be imported or exported from a repository using the
433 \fBsvccfg\fR(1M) command. See \fBservice_bundle\fR(4) for a description of the
434 service bundle file format with guidelines for authoring service bundles.
435 .sp
436 .LP
437 A \fIservice archive\fR is an XML file that contains the description and
438 persistent properties of every service in the repository, excluding transient
439 properties such as service state. This service archive is basically a 'svccfg
440 export' for every service which is not limited to named services.
441 .SS "Milestones"
442 .sp
443 .LP
444 An \fBsmf\fR milestone is a service that aggregates a multiple service
445 dependencies. Usually, a milestone does nothing useful itself, but declares a
446 specific state of system-readiness on which other services can depend. One
447 example is the \fBname-services\fR milestone, which simply depends upon the
448 currently enabled name services.
449 .SS "Legacy Startup Scripts"
450 .sp
451 .LP
452 Startup programs in the \fB/etc/rc?.d\fR directories are executed as part of
453 the corresponding run-level milestone:
454 .sp
455 .ne 2
456 .na
457 \fB\fB/etc/rcS.d\fR\fR
458 .ad
459 .RS 14n
460 milestone/single-user:default
461 .RE
463 .sp
464 .ne 2
465 .na
466 \fB\fB/etc/rc2.d\fR\fR
467 .ad
468 .RS 14n
469 milestone/multi-user:default
470 .RE
472 .sp
473 .ne 2
474 .na
475 \fB\fB/etc/rc3.d\fR\fR
476 .ad
477 .RS 14n
478 milestone/multi-user-server:default
479 .RE
481 .sp
482 .LP
483 Execution of each program is represented as a reduced-functionality service
484 instance named by the program's path. These instances are held in a special
485 legacy-run state.
486 .sp
487 .LP
488 These instances do not have an enabled property (type \fBboolean\fR in the
489 general property group) and, generally, cannot be manipulated with the
490 \fBsvcadm\fR(1M) command. No error diagnosis or restart is done for these
491 programs.
492 .SH SEE ALSO
493 .sp
494 .LP
495 \fBsvcs\fR(1), \fBinetd\fR(1M), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M),
496 \fBsvc.configd\fR(1M), \fBsvc.startd\fR(1M), \fBexec\fR(2), \fBfork\fR(2),
497 \fBlibscf\fR(3LIB), \fBstrftime\fR(3C), \fBcontract\fR(4),
498 \fBservice_bundle\fR(4), \fBsmf_bootstrap\fR(5), \fBsmf_method\fR(5),
499 \fBsmf_restarter\fR(5), \fBsmf_security\fR(5)