Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  de-
       vice,  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  in-
       formation.  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 de-
       pendencies  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, in-
       etd(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 po-
       tential receipt of events from the contracts filesystem.	The  following
       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 ex-
		       pected  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. Us-
       ing  property groups in this way	allows the configuration of the	appli-
       cation to derive	the attributes that the	repository  provides  for  all
       data in the facility. The application can also use the appropriate sub-
       set 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  in-
		       stances.

       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)

NAME | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=smf&sektion=5&manpath=SunOS+5.10>

home | help