Resource Type: service

NOTE: This page was generated from the Puppet source code on 2024-09-30 11:26:40 -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:

Attributes

service { 'resource title':
  name          => # (namevar) The name of the service to run.  This name is...
  ensure        => # Whether a service should be running. Default...
  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...
  logonaccount  => # Specify an account for service...
  logonpassword => # Specify a password for service logon. Default...
  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...
  timeout       => # Specify an optional minimum timeout (in seconds) 
  # ...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. Default values depend on the platform.

Allowed values:

(↑ 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 differently depending on the platform; wherever possible, it relies on local tools to enable or disable a given service. Default values depend on the platform.

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:

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.

Allowed values:

(↑ Back to service attributes)

hasstatus

Declare whether the service’s init script has a functional status command. 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:

(↑ Back to service attributes)

logonaccount

(Property: This attribute represents concrete state on the target system.)

Specify an account for service logon

Requires features manages_logon_credentials.

(↑ Back to service attributes)

logonpassword

Specify a password for service logon. Default value is an empty string (when logonaccount is specified).

Requires features manages_logon_credentials.

(↑ 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:

(↑ 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)

timeout

Specify an optional minimum timeout (in seconds) for puppet to wait when syncing service properties

Requires features configurable_timeout.

(↑ 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.

bsd

Generic BSD form of init-style service management with rc.d.

Uses rc.conf.d for service enabling and disabling.

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:

The daemon directory should be in one of the following locations:

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

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.

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.

freebsd

Provider for FreeBSD and DragonFly BSD. Uses the rcvar argument of init scripts and parses/edits rc files.

gentoo

Gentoo’s form of init-style service management.

Uses rc-update for service enabling and disabling.

init

Standard init-style service management.

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:

…and builds up a list of services based upon each plist’s “Label” entry.

This provider supports:

Here is how the Puppet states correspond to launchd states:

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’

openbsd

Provider for OpenBSD’s rc.d daemon control scripts

openrc

Support for Gentoo’s OpenRC initskripts

Uses rc-update, rc-status and rc-service to manage services.

openwrt

Support for OpenWrt flavored init scripts.

Uses /etc/init.d/service_name enable, disable, and enabled.

rcng

RCng service management with rc.d

redhat

Red Hat’s (and probably many others’) form of init-style service management. Uses chkconfig for service enabling and disabling.

runit

Runit service management.

This provider manages daemons running supervised by Runit. When detecting the service directory it will check, in order of preference:

The daemon directory should be in one of the following locations:

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:

service

The simplest form of service support.

smf

Support for Sun’s new Service Management Framework.

When managing the enable property, this provider will try to preserve the previous ensure state per the enableable semantics. On Solaris, enabling a service starts it up while disabling a service stops it. Thus, there’s a chance for this provider to execute two operations when managing the enable property. For example, if enable is set to true and the ensure state is stopped, this provider will manage the service using two operations: one to enable the service which will start it up, and another to stop the service (without affecting its enabled status).

By specifying manifest => "/path/to/service.xml", the SMF manifest will be imported if it does not exist.

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.

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.

upstart

Ubuntu service management with upstart.

This provider manages upstart jobs on Ubuntu. For upstart documentation, see http://upstart.ubuntu.com/.

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.

Provider Features

Available features:

Provider support: