Use the service resource to manage a service.
A service resource block manages the state of a service. For example:
service "tomcat" do action :start end
will start the Apache Tomcat service.
The full syntax for all of the properties that are available to the service resource is:
service 'name' do init_command String notifies # see description pattern String priority Integer, String, Hash provider Chef::Provider::Service reload_command String restart_command String service_name String # defaults to 'name' if not specified start_command String status_command String stop_command String subscribes # see description supports Hash timeout Integer # Microsoft Windows only action Symbol # defaults to :nothing if not specified end
where
service
is the resource; depending on the platform, more specific providers are run: Chef::Provider::Service::Init
, Chef::Provider::Service::Init::Debian
, Chef::Provider::Service::Upstart
, Chef::Provider::Service::Init::Freebsd
, Chef::Provider::Service::Init::Gentoo
, Chef::Provider::Service::Init::Redhat
, Chef::Provider::Service::Solaris
, Chef::Provider::Service::Windows
, or Chef::Provider::Service::Macosx
name
is the name of the resource block; when the path
property is not specified, name
is also the path to the directory, from the root:action
identifies the steps the chef-client will take to bring the node into the desired stateinit_command
, pattern
, priority
, provider
, reload_command
, restart_command
, service_name
, start_command
, status_command
, stop_command
, supports
, and timeout
are properties of this resource, with the Ruby type shown. See “Properties” section below for more information about all of the properties that may be used with this resource.This resource has the following actions:
:disable
Disabled
startup type on the Microsoft Windows platform. This action is not supported when using System Resource Controller (SRC) on the AIX platform because System Resource Controller (SRC) does not have a standard mechanism for enabling and disabling services on system boot.:enable
Automatic
startup type on the Microsoft Windows platform. This action is not supported when using System Resource Controller (SRC) on the AIX platform because System Resource Controller (SRC) does not have a standard mechanism for enabling and disabling services on system boot.:nothing
:reload
:restart
:start
:stop
Note
To mange a Microsoft Windows service with a Manual
startup type, the windows_service resource must be used.
This resource has the following properties:
ignore_failure
Ruby Types: TrueClass, FalseClass
Continue running a recipe if a resource fails for any reason. Default value: false
.
init_command
Ruby Type: String
The path to the init script that is associated with the service. Use init_command
to prevent the need to specify overrides for the start_command
, stop_command
, and restart_command
properties. When this property is not specified, the chef-client will use the default init command for the service provider being used.
notifies
Ruby Type: Symbol, ‘Chef::Resource[String]’
A resource may notify another resource to take action when its state changes. Specify a 'resource[name]'
, the :action
that resource should take, and then the :timer
for that action. A resource may notifiy more than one resource; use a notifies
statement for each resource to be notified.
A timer specifies the point during the chef-client run at which a notification is run. The following timers are available:
:before
:delayed
:immediate
, :immediately
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
pattern
Ruby Type: String
The pattern to look for in the process table. Default value: service_name
.
priority
Ruby Types: Integer, String, Hash
Debian platform only. The relative priority of the program for start and shutdown ordering. May be an integer or a Hash. An integer is used to define the start run levels; stop run levels are then 100-integer. A Hash is used to define values for specific run levels. For example, { 2 => [:start, 20], 3 => [:stop, 55] }
will set a priority of twenty for run level two and a priority of fifty-five for run level three.
provider
Ruby Type: Chef Class
Optional. Explicitly specifies a provider. See “Providers” section below for more information.
reload_command
Ruby Type: String
The command used to tell a service to reload its configuration.
restart_command
Ruby Type: String
The command used to restart a service.
retries
Ruby Type: Integer
The number of times to catch exceptions and retry the resource. Default value: 0
.
retry_delay
Ruby Type: Integer
The retry delay (in seconds). Default value: 2
.
service_name
Ruby Type: String
The name of the service. Default value: the name
of the resource block See “Syntax” section above for more information.
start_command
Ruby Type: String
The command used to start a service.
status_command
Ruby Type: String
The command used to check the run status for a service.
stop_command
Ruby Type: String
The command used to stop a service.
subscribes
Ruby Type: Symbol, ‘Chef::Resource[String]’
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a 'resource[name]'
, the :action
to be taken, and then the :timer
for that action.
A timer specifies the point during the chef-client run at which a notification is run. The following timers are available:
:before
:delayed
:immediate
, :immediately
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
supports
Ruby Type: Hash
A list of properties that controls how the chef-client is to attempt to manage a service: :restart
, :reload
, :status
. For :restart
, the init script or other service provider can use a restart command; if :restart
is not specified, the chef-client attempts to stop and then start a service. For :reload
, the init script or other service provider can use a reload command. For :status
, the init script or other service provider can use a status command to determine if the service is running; if :status
is not specified, the chef-client attempts to match the service_name
against the process table as a regular expression, unless a pattern is specified as a parameter property. Default value: { :restart => false, :reload => false, :status => false }
for all platforms (except for the Red Hat platform family, which defaults to { :restart => false, :reload => false, :status => true }
.)
timeout
Ruby Type: Integer
Microsoft Windows platform only. The amount of time (in seconds) to wait before timing out. Default value: 60
.
Where a resource represents a piece of the system (and its desired state), a provider defines the steps that are needed to bring that piece of the system from its current state into the desired state.
The chef-client will determine the correct provider based on configuration data collected by Ohai at the start of the chef-client run. This configuration data is then mapped to a platform and an associated list of providers.
Generally, it’s best to let the chef-client choose the provider, and this is (by far) the most common approach. However, in some cases, specifying a provider may be desirable. There are two approaches:
yum_package "foo" do
instead of package "foo" do
, script "foo" do
instead of bash "foo" do
, and so on—when availableprovider
property within the resource block to specify the long name of the provider as a property of a resource. For example: provider Chef::Provider::Long::Name
The service resource does not have service-specific short names. This is because the chef-client identifies the platform at the start of every chef-client run based on data collected by Ohai. The chef-client looks up the platform, and then determines the correct provider for that platform. In certain situations, such as when more than one init system is available on a node, a specific provider may need to be identified by using the provider
attribute and the long name for that provider.
This resource has the following providers:
Chef::Provider::Service::Init
, service
Chef::Provider::Service::Aix
, service
Chef::Provider::Service::AixInit
Chef::Provider::Service::AixInit
—in a recipe to manage services with BSD-based init systems on the AIX platform.Chef::Provider::Service::Init::Debian
, service
Chef::Provider::Service::Init::Freebsd
, service
Chef::Provider::Service::Init::Gentoo
, service
Chef::Provider::Service::Init::Redhat
, service
Chef::Provider::Service::Simple
provider
attribute.Chef::Provider::Service::Solaris
, service
Chef::Provider::Service::Systemd
, systemd
Chef::Provider::Service::Upstart
, service
Chef::Provider::Service::Windows
, service
Chef::Provider::Service::Macosx
, service
The following examples demonstrate various approaches for using resources in recipes. If you want to see examples of how Chef uses resources in recipes, take a closer look at the cookbooks that Chef authors and maintains: https://github.com/chef-cookbooks.
Start a service
service 'example_service' do action :start end
Start a service, enable it
service 'example_service' do supports :status => true, :restart => true, :reload => true action [ :enable, :start ] end
Use a pattern
service 'samba' do pattern 'smbd' action [:enable, :start] end
Use the :nothing common action
service 'memcached' do action :nothing supports :status => true, :start => true, :stop => true, :restart => true end
Use the supports common attribute
service 'apache' do supports :restart => true, :reload => true action :enable end
Use the supports and providers common attributes
service 'some_service' do provider Chef::Provider::Service::Upstart supports :status => true, :restart => true, :reload => true action [ :enable, :start ] end
Manage a service, depending on the node platform
service 'example_service' do case node['platform'] when 'centos','redhat','fedora' service_name 'redhat_name' else service_name 'other_name' end supports :restart => true action [ :enable, :start ] end
Change a service provider, depending on the node platform
service 'example_service' do case node['platform'] when 'ubuntu' if node['platform_version'].to_f >= 9.10 provider Chef::Provider::Service::Upstart end end action [:enable, :start] end
Reload a service using a template
To reload a service based on a template, use the template and service resources together in the same recipe, similar to the following:
template '/tmp/somefile' do mode '0755' source 'somefile.erb' end service 'apache' do supports :restart => true, :reload => true action :enable subscribes :reload, 'template[/tmp/somefile]', :immediately end
where the subscribes
notification is used to reload the service using the template specified by the template resource.
Enable a service after a restart or reload
service 'apache' do supports :restart => true, :reload => true action :enable end
Set an IP address using variables and a template
The following example shows how the template resource can be used in a recipe to combine settings stored in an attributes file, variables within a recipe, and a template to set the IP addresses that are used by the Nginx service. The attributes file contains the following:
default['nginx']['dir'] = '/etc/nginx'
The recipe then does the following to:
authorized_ip.erb
from the /templates
directory that is used to set the IP address values based on the variables specified in the recipenode.default['nginx']['remote_ip_var'] = 'remote_addr' node.default['nginx']['authorized_ips'] = ['127.0.0.1/32'] service 'nginx' do supports :status => true, :restart => true, :reload => true end template 'authorized_ip' do path "#{node['nginx']['dir']}/authorized_ip" source 'modules/authorized_ip.erb' owner 'root' group 'root' mode '0755' variables( :remote_ip_var => node['nginx']['remote_ip_var'], :authorized_ips => node['nginx']['authorized_ips'] ) notifies :reload, 'service[nginx]', :immediately end
where the variables
property tells the template to use the variables set at the beginning of the recipe and the source
property is used to call a template file located in the cookbook’s /templates
directory. The template file looks similar to:
geo $<%= @remote_ip_var %> $authorized_ip { default no; <% @authorized_ips.each do |ip| %> <%= "#{ip} yes;" %> <% end %> }
Use a cron timer to manage a service
The following example shows how to install the crond application using two resources and a variable:
# the following code sample comes from the ``cron`` cookbook: # https://github.com/chef-cookbooks/cron cron_package = case node['platform'] when 'redhat', 'centos', 'scientific', 'fedora', 'amazon' node['platform_version'].to_f >= 6.0 ? 'cronie' : 'vixie-cron' else 'cron' end package cron_package do action :install end service 'crond' do case node['platform'] when 'redhat', 'centos', 'scientific', 'fedora', 'amazon' service_name 'crond' when 'debian', 'ubuntu', 'suse' service_name 'cron' end action [:start, :enable] end
where
cron_package
is a variable that is used to identify which platforms apply to which install packagescron_package
variable to determine how to install the crond application on various nodes (with various platforms)Restart a service, and then notify a different service
The following example shows how start a service named example_service
and immediately notify the Nginx service to restart.
service 'example_service' do action :start provider Chef::Provider::Service::Init notifies :restart, 'service[nginx]', :immediately end
where by using the default provider
for the service, the recipe is telling the chef-client to determine the specific provider to be used during the chef-client run based on the platform of the node on which the recipe will run.
Stop a service, do stuff, and then restart it
The following example shows how to use the execute, service, and mount resources together to ensure that a node running on Amazon EC2 is running MySQL. This example does the following:
# the following code sample comes from the ``server_ec2`` # recipe in the following cookbook: # https://github.com/chef-cookbooks/mysql if (node.attribute?('ec2') && ! FileTest.directory?(node['mysql']['ec2_path'])) service 'mysql' do action :stop end execute 'install-mysql' do command "mv #{node['mysql']['data_dir']} #{node['mysql']['ec2_path']}" not_if do FileTest.directory?(node['mysql']['ec2_path']) end end [node['mysql']['ec2_path'], node['mysql']['data_dir']].each do |dir| directory dir do owner 'mysql' group 'mysql' end end mount node['mysql']['data_dir'] do device node['mysql']['ec2_path'] fstype 'none' options 'bind,rw' action [:mount, :enable] end service 'mysql' do action :start end end
where
Control a service using the execute resource
Warning
This is an example of something that should NOT be done. Use the service resource to control a service, not the execute resource.
Do something like this:
service 'tomcat' do action :start end
and NOT something like this:
execute 'start-tomcat' do command '/etc/init.d/tomcat6 start' action :run end
There is no reason to use the execute resource to control a service because the service resource exposes the start_command
property directly, which gives a recipe full control over the command issued in a much cleaner, more direct manner.
Enable a service on AIX using the mkitab command
The service resource does not support using the :enable
and :disable
actions with resources that are managed using System Resource Controller (SRC). This is because System Resource Controller (SRC) does not have a standard mechanism for enabling and disabling services on system boot.
One approach for enabling or disabling services that are managed by System Resource Controller (SRC) is to use the execute resource to invoke mkitab
, and then use that command to enable or disable the service.
The following example shows how to install a service:
execute "install #{node['chef_client']['svc_name']} in SRC" do command "mkssys -s #{node['chef_client']['svc_name']} -p #{node['chef_client']['bin']} -u root -S -n 15 -f 9 -o #{node['chef_client']['log_dir']}/client.log -e #{node['chef_client']['log_dir']}/client.log -a ' -i #{node['chef_client']['interval']} -s #{node['chef_client']['splay']}'" not_if "lssrc -s #{node['chef_client']['svc_name']}" action :run end
and then enable it using the mkitab
command:
execute "enable #{node['chef_client']['svc_name']}" do command "mkitab '#{node['chef_client']['svc_name']}:2:once:/usr/bin/startsrc -s #{node['chef_client']['svc_name']} > /dev/console 2>&1'" not_if "lsitab #{node['chef_client']['svc_name']}" end
© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs-archive.chef.io/release/12-13/resource_service.html