unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

smf(5)                Standards, Environments, and Macros               smf(5)



NAME
       smf - service management facility

DESCRIPTION
       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:

       svc://localhost/system/system-log:default
       svc:/system/system-log:default
       system/system-log:default


       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.

   Dependencies
       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).

   Restarters
       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).

   Methods
       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
       page.

       The  methods  for  a  service can be listed and modified using the svc-
       cfg(1M) command.

   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 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
                       appropriate restarter.



       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-
       nating state.

   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.
       See smf_security(5).

   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  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-
                       erty customization.



       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.

   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  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
       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 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
                       instances.



       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
       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 and, generally, cannot
       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),  con-
       tract(4),      service_bundle(4),      user_attr(4),     smf_method(5),
       smf_restarter(5), smf_security(5)



SunOS 5.10                        2 Dec 2004                            smf(5)