Resource Type: service
NOTE: This page was generated from the Puppet source code on 2018-08-28 06:48:02 -0700 service —–
Description
Manage running services. Service support unfortunately varies widely by platform — some platforms have very little if any concept of a running service, and some have a very codified and powerful concept. Puppet’s service support is usually capable of doing the right thing, but the more information you can provide, the better behaviour you will get.
Puppet 2.7 and newer expect init scripts to have a working status command.
If this isn’t the case for any of your services’ init scripts, you will
need to set hasstatus
to false and possibly specify a custom status
command in the status
attribute. As a last resort, Puppet will attempt to
search the process table by calling whatever command is listed in the ps
fact. The default search pattern is the name of the service, but you can
specify it with the pattern
attribute.
Refresh: service
resources can respond to refresh events (via
notify
, subscribe
, or the ~>
arrow). If a service
receives an
event from another resource, Puppet will restart the service it manages.
The actual command used to restart the service depends on the platform and
can be configured:
- If you set
hasrestart
to true, Puppet will use the init script’s restart command. - You can provide an explicit command for restarting with the
restart
attribute. - If you do neither, the service’s stop and start commands will be used.
Attributes
service { 'resource title':
name => # (namevar) The name of the service to run. This name is...
ensure => # Whether a service should be running. Valid...
binary => # The path to the daemon. This is only used for...
control => # The control variable used to manage services...
enable => # Whether a service should be enabled to start at...
flags => # Specify a string of flags to pass to the startup
hasrestart => # Specify that an init script has a `restart...
hasstatus => # Declare whether the service's init script has a...
manifest => # Specify a command to config a service, or a path
path => # The search path for finding init scripts....
pattern => # The pattern to search for in the process table...
provider => # The specific backend to use for this `service...
restart => # Specify a *restart* command manually. If left...
start => # Specify a *start* command manually. Most...
status => # Specify a *status* command manually. This...
stop => # Specify a *stop* command...
# ...plus any applicable metaparameters.
}
name
(Namevar: If omitted, this attribute’s value defaults to the resource’s title.)
The name of the service to run.
This name is used to find the service; on platforms where services have short system names and long display names, this should be the short name. (To take an example from Windows, you would use “wuauserv” rather than “Automatic Updates.”)
(↑ Back to service attributes)
ensure
(Property: This attribute represents concrete state on the target system.)
Whether a service should be running.
Allowed values:
-
stopped
orfalse
-
running
ortrue
(↑ Back to service attributes)
binary
The path to the daemon. This is only used for
systems that do not support init scripts. This binary will be
used to start the service if no start
parameter is
provided.
(↑ Back to service attributes)
control
The control variable used to manage services (originally for HP-UX).
Defaults to the upcased service name plus START
replacing dots with
underscores, for those providers that support the controllable
feature.
(↑ Back to service attributes)
enable
(Property: This attribute represents concrete state on the target system.)
Whether a service should be enabled to start at boot. This property behaves quite differently depending on the platform; wherever possible, it relies on local tools to enable or disable a given service.
If you don’t specify a value for the enable
attribute, Puppet leaves that aspect of the service alone and your operating system determines the behavior.
Allowed values:
true
false
manual
mask
Requires features enableable.
(↑ Back to service attributes)
flags
(Property: This attribute represents concrete state on the target system.)
Specify a string of flags to pass to the startup script.
Requires features flaggable.
(↑ Back to service attributes)
hasrestart
Specify that an init script has a restart
command. If this is
false and you do not specify a command in the restart
attribute,
the init script’s stop
and start
commands will be used.
Defaults to false.
Allowed values:
true
false
(↑ Back to service attributes)
hasstatus
Declare whether the service’s init script has a functional status
command; defaults to true
. This attribute’s default value changed in
Puppet 2.7.0.
The init script’s status command must return 0 if the service is running and a nonzero value otherwise. Ideally, these exit codes should conform to the LSB’s specification for init script status actions, but Puppet only considers the difference between 0 and nonzero to be relevant.
If a service’s init script does not support any kind of status command,
you should set hasstatus
to false and either provide a specific
command using the status
attribute or expect that Puppet will look for
the service name in the process table. Be aware that ‘virtual’ init
scripts (like ‘network’ under Red Hat systems) will respond poorly to
refresh events from other resources if you override the default behavior
without providing a status command.
Default: true
Allowed values:
true
false
(↑ Back to service attributes)
manifest
Specify a command to config a service, or a path to a manifest to do so.
(↑ Back to service attributes)
path
The search path for finding init scripts. Multiple values should be separated by colons or provided as an array.
(↑ Back to service attributes)
pattern
The pattern to search for in the process table. This is used for stopping services on platforms that do not support init scripts, and is also used for determining service status on those service whose init scripts do not include a status command.
Defaults to the name of the service. The pattern can be a simple string or any legal Ruby pattern, including regular expressions (which should be quoted without enclosing slashes).
(↑ Back to service attributes)
provider
The specific backend to use for this service
resource. You will seldom need to specify this — Puppet will usually
discover the appropriate provider for your platform.
Available providers are:
base
bsd
daemontools
debian
freebsd
gentoo
init
launchd
openbsd
openrc
openwrt
rcng
redhat
runit
service
smf
src
systemd
upstart
windows
(↑ Back to service attributes)
restart
Specify a restart command manually. If left unspecified, the service will be stopped and then started.
(↑ Back to service attributes)
start
Specify a start command manually. Most service subsystems
support a start
command, so this will not need to be
specified.
(↑ Back to service attributes)
status
Specify a status command manually. This command must return 0 if the service is running and a nonzero value otherwise. Ideally, these exit codes should conform to the LSB’s specification for init script status actions, but Puppet only considers the difference between 0 and nonzero to be relevant.
If left unspecified, the status of the service will be determined automatically, usually by looking for the service in the process table.
(↑ Back to service attributes)
stop
Specify a stop command manually.
(↑ Back to service attributes)
Providers
base
The simplest form of Unix service support.
You have to specify enough about your service for this to work; the
minimum you can specify is a binary for starting the process, and this
same binary will be searched for in the process table to stop the
service. As with init
-style services, it is preferable to specify start,
stop, and status commands.
- Required binaries:
kill
- Supported features:
refreshable
bsd
Generic BSD form of init
-style service management with rc.d
.
Uses rc.conf.d
for service enabling and disabling.
- Confined to:
operatingsystem == [:freebsd, :dragonfly]
- Supported features:
enableable
,refreshable
.
daemontools
Daemontools service management.
This provider manages daemons supervised by D.J. Bernstein daemontools. When detecting the service directory it will check, in order of preference:
/service
/etc/service
/var/lib/svscan
The daemon directory should be in one of the following locations:
/var/lib/service
/etc
…or this can be overridden in the resource’s attributes:
service { 'myservice':
provider => 'daemontools',
path => '/path/to/daemons',
}
This provider supports out of the box:
- start/stop (mapped to enable/disable)
- enable/disable
- restart
- status
If a service has ensure => "running"
, it will link /path/to/daemon to
/path/to/service, which will automatically enable the service.
If a service has ensure => "stopped"
, it will only shut down the service, not
remove the /path/to/service
link.
- Required binaries:
/usr/bin/svc
,/usr/bin/svstat
- Supported features:
enableable
,refreshable
debian
Debian’s form of init
-style management.
The only differences from init
are support for enabling and disabling
services via update-rc.d
and the ability to determine enabled status via
invoke-rc.d
.
- Required binaries:
/usr/sbin/update-rc.d
,/usr/sbin/invoke-rc.d
,/usr/sbin/service
- Default for:
["operatingsystem", "cumuluslinux"] == ["operatingsystemmajrelease", "['1','2']"]
,["operatingsystem", "debian"] == ["operatingsystemmajrelease", "['5','6','7']"]
- Supported features:
enableable
,refreshable
.
freebsd
Provider for FreeBSD and DragonFly BSD. Uses the rcvar
argument of init scripts and parses/edits rc files.
- Confined to:
operatingsystem == [:freebsd, :dragonfly]
- Default for
operatingsystem
==freebsd, dragonfly
. - Supported features:
enableable
,refreshable
.
gentoo
Gentoo’s form of init
-style service management.
Uses rc-update
for service enabling and disabling.
- Required binaries:
/sbin/rc-update
- Confined to:
operatingsystem == gentoo
- Supported features:
enableable
,refreshable
init
Standard init
-style service management.
-
Confined to:
true == begin os = Facter.value(:operatingsystem).downcase family = Facter.value(:osfamily).downcase !(os == 'debian' || os == 'ubuntu' || family == 'redhat') end
-
Supported features:
refreshable
launchd
This provider manages jobs with launchd
, which is the default service
framework for Mac OS X (and may be available for use on other platforms).
For more information, see the launchd
man page:
This provider reads plists out of the following directories:
/System/Library/LaunchDaemons
/System/Library/LaunchAgents
/Library/LaunchDaemons
/Library/LaunchAgents
…and builds up a list of services based upon each plist’s “Label” entry.
This provider supports:
- ensure => running/stopped,
- enable => true/false
- status
- restart
Here is how the Puppet states correspond to launchd
states:
- stopped — job unloaded
- started — job loaded
- enabled — ‘Disable’ removed from job plist file
- disabled — ‘Disable’ added to job plist file
Note that this allows you to do something launchctl
can’t do, which is to
be in a state of “stopped/enabled” or “running/disabled”.
Note that this provider does not support overriding ‘restart’
- Required binaries:
/bin/launchctl
- Confined to:
operatingsystem == darwin
,feature == cfpropertylist
- Default for
operatingsystem
==darwin
- Supported features:
enableable
,refreshable
openbsd
Provider for OpenBSD’s rc.d daemon control scripts
- Required binaries:
/usr/sbin/rcctl
- Confined to:
operatingsystem == openbsd
- Default for
operatingsystem
==openbsd
- Supported features:
enableable
,flaggable
,refreshable
openrc
Support for Gentoo’s OpenRC initskripts
Uses rc-update, rc-status and rc-service to manage services.
- Required binaries:
/sbin/rc-service
,/sbin/rc-update
- Default for
operatingsystem
==gentoo
,operatingsystem
==funtoo
. - Supported features:
enableable
,refreshable
openwrt
Support for OpenWrt flavored init scripts.
Uses /etc/init.d/service_name enable, disable, and enabled.
- Confined to:
operatingsystem == openwrt
- Default for
operatingsystem
==openwrt
- Supported features:
enableable
,refreshable
rcng
RCng service management with rc.d
- Confined to:
operatingsystem == [:netbsd, :cargos]
- Default for
operatingsystem
==netbsd, cargos
- Supported features:
enableable
,refreshable
redhat
Red Hat’s (and probably many others’) form of init
-style service
management. Uses chkconfig
for service enabling and disabling.
- Required binaries:
/sbin/chkconfig
,/sbin/service
- Default for
osfamily
==redhat
,operatingsystemmajrelease
==10, 11
andosfamily
==suse
- Supported features:
enableable
,refreshable
runit
Runit service management.
This provider manages daemons running supervised by Runit. When detecting the service directory it will check, in order of preference:
/service
/etc/service
/var/service
The daemon directory should be in one of the following locations:
/etc/sv
/var/lib/service
or this can be overridden in the service resource parameters:
service { 'myservice':
provider => 'runit',
path => '/path/to/daemons',
}
This provider supports out of the box:
- start/stop
- enable/disable
- restart
-
status
- Required binaries:
/usr/bin/sv
- Supported features:
enableable
,refreshable
service
The simplest form of service support.
- Supported features:
refreshable
smf
Support for Sun’s new Service Management Framework.
Starting a service is effectively equivalent to enabling it, so there is only support for starting and stopping services, which also enables and disables them, respectively.
By specifying manifest => "/path/to/service.xml"
, the SMF manifest will
be imported if it does not exist.
- Required binaries:
/usr/sbin/svcadm
,/usr/bin/svcs
,/usr/sbin/svccfg
- Confined to:
osfamily == solaris
- Default for
osfamily
==solaris
- Supported features:
enableable
,refreshable
src
Support for AIX’s System Resource controller.
Services are started/stopped based on the stopsrc
and startsrc
commands, and some services can be refreshed with refresh
command.
Enabling and disabling services is not supported, as it requires
modifications to /etc/inittab
. Starting and stopping groups of subsystems
is not yet supported.
- Required binaries:
/usr/bin/lssrc
,/usr/bin/refresh
,/usr/bin/startsrc
,/usr/bin/stopsrc
,/usr/sbin/chitab
,/usr/sbin/lsitab
,/usr/sbin/mkitab
,/usr/sbin/rmitab
- Confined to:
operatingsystem == aix
- Default for
operatingsystem
==aix
- Supported features:
enableable
,refreshable
systemd
Manages systemd
services using systemctl
.
Because systemd
defaults to assuming the .service
unit type, the suffix
may be omitted. Other unit types (such as .path
) may be managed by
providing the proper suffix.
- Required binaries:
systemctl
- Default for
-
osfamily
==archlinux
-
operatingsystemmajrelease
==7
andosfamily
==redhat
-
operatingsystem
==fedora
andosfamily
==redhat
-
osfamily
==suse
-
osfamily
==coreos
-
operatingsystem
==amazon
andoperatingsystemmajrelease
==2
-
operatingsystem
==debian
andoperatingsystemmajrelease
==8, stretch/sid, 9, buster/sid
-
operatingsystem
==ubuntu
andoperatingsystemmajrelease
==15.04, 15.10, 16.04, 16.10, 17.04, 17.10, 18.04
-
operatingsystem
==cumuluslinux
andoperatingsystemmajrelease
==3
.
-
- Supported features:
enableable
,maskable
,refreshable
upstart
Ubuntu service management with upstart
.
This provider manages upstart
jobs on Ubuntu. For upstart
documentation,
see http://upstart.ubuntu.com/.
- Required binaries:
/sbin/start
,/sbin/stop
,/sbin/restart
,/sbin/status
,/sbin/initctl
- Confined to:
any == [ Facter.value(:operatingsystem) == 'Ubuntu', (Facter.value(:osfamily) == 'RedHat' and Facter.value(:operatingsystemrelease) =~ /^6\./), (Facter.value(:operatingsystem) == 'Amazon' and Facter.value(:operatingsystemmajrelease) =~ /\d{4}/), Facter.value(:operatingsystem) == 'LinuxMint', ]
exists == /var/run/upstart-socket-bridge.pid
- Default for
operatingsystem
==ubuntu
andoperatingsystemmajrelease
==10.04, 12.04, 14.04, 14.10
- Supported features:
enableable
,refreshable
windows
Support for Windows Service Control Manager (SCM). This provider can start, stop, enable, and disable services, and the SCM provides working status methods for all services.
Control of service groups (dependencies) is not yet supported, nor is running services as a specific user.
- Required binaries:
net.exe
- Confined to:
operatingsystem == windows
- Default for
operatingsystem
==windows
- Supported features:
enableable
,refreshable
Provider Features
Available features:
-
controllable
— The provider uses a control variable. -
enableable
— The provider can enable and disable the service -
flaggable
— The provider can pass flags to the service. -
maskable
— The provider can ‘mask’ the service. -
refreshable
— The provider can restart the service.
Provider support:
Provider | controllable | enableable | flaggable | maskable | refreshable |
---|---|---|---|---|---|
base | X | ||||
bsd | X | X | |||
daemontools | X | X | |||
debian | X | X | |||
freebsd | X | X | |||
gentoo | X | X | |||
init | X | ||||
launchd | X | X | |||
openbsd | X | X | X | ||
openrc | X | X | |||
openwrt | X | X | |||
rcng | X | X | |||
redhat | X | X | |||
runit | X | X | |||
service | X | ||||
smf | X | X | |||
src | X | X | |||
systemd | X | X | X | ||
upstart | X | X | |||
windows | X | X |
NOTE: This page was generated from the Puppet source code on 2018-08-28 06:48:02 -0700