1smf(5)                Standards, Environments, and Macros               smf(5)
2
3
4

NAME

6       smf - service management facility
7

DESCRIPTION

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
22
23       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
27         svc://localhost/system/system-log:default
28         svc:/system/system-log:default
29         system/system-log:default
30
31
32
33       Many commands also allow FMRI abbreviations. See the svcs(1)  man  page
34       for one such example.
35
36
37       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
43
44       A  service  instance is either enabled or disabled. All services can be
45       enabled or disabled with the svcadm(1M) command.
46
47
48       The list of managed service instances on a system can be displayed with
49       the svcs(1) command.
50
51   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
59
60       Whether a dependency is satisfied is determined by its grouping:
61
62       require_all     Satisfied when all cited services are  running  (online
63                       or degraded), or when all indicated files are present.
64
65
66       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
70
71       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
77
78       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
82
83
84       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
89                            |  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
96
97
98       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
103
104       The dependencies on a service can be listed with svcs(1) or svccfg(1M),
105       and modified with svccfg(1M).
106
107   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
119
120       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
124
125       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
129   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
135
136       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
140
141       The methods for a service can be listed and  modified  using  the  svc‐
142       cfg(1M) command.
143
144   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
149       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
154
155       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
162
163       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
173
174       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
183
184       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
190
191       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
195
196       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
203
204
205       States  can also have transitions that result in a return to the origi‐
206       nating state.
207
208   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
219
220       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
228
229       Properties are protected from modification by  unauthorized  processes.
230       See smf_security(5).
231
232   General Property Group
233       The  general  property  group  applies  to  all  service  instances. It
234       includes the following properties:
235
236       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
241
242       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
246
247   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
253       initial        Initial configuration of the  instance  created  by  the
254                      administrator or produced during package installation.
255
256
257       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
262
263       previous       Current configuration captured  when  an  administrative
264                      undo operation is performed.
265
266
267       running        The running configuration of the instance.
268
269
270       start          Configuration captured during a successful transition to
271                      the online state.
272
273
274
275       The svccfg(1M) command can be used to interact with snapshots.
276
277   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
283   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
290
291       The  repository  for  service  management  facility  data is managed by
292       svc.configd(1M).
293
294   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
301       manifests    Files that contain the complete set of properties  associ‐
302                    ated with a specific set of services or service instances.
303
304
305       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
309                    Profiles can also contain configuration values for proper‐
310                    ties in services and instances. Template  elements  cannot
311                    be defined in a profile.
312
313
314
315       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
319
320       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
326   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
333   Legacy Startup Scripts
334       Startup  programs in the /etc/rc?.d directories are executed as part of
335       the corresponding run-level milestone:
336
337       /etc/rcS.d    milestone/single-user:default
338
339
340       /etc/rc2.d    milestone/multi-user:default
341
342
343       /etc/rc3.d    milestone/multi-user-server:default
344
345
346
347       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
351
352       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

SEE ALSO

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)
362
363
364
365SunOS 5.11                        6 Jul 2009                            smf(5)
Impressum