Use the launchd resource to manage system-wide services (daemons) and per-user services (agents) on the Mac OS X platform.
A launchd resource manages system-wide services (daemons) and per-user services (agents) on the Mac OS X platform:
launchd 'call.mom.weekly' do program '/Library/scripts/call_mom.sh' start_calendar_interval 'weekday' => 7, 'hourly' => 10 time_out 300 end
The full syntax for all of the properties that are available to the launchd resource is:
launchd 'name' do abandon_process_group TrueClass, FalseClass backup Integer, FalseClass cookbook String debug TrueClass, FalseClass disabled TrueClass, FalseClass enable_globbing TrueClass, FalseClass enable_transactions TrueClass, FalseClass environment_variables Hash exit_timeout Integer group String, Integer hard_resource_limits Hash hash Hash ignore_failure TrueClass, FalseClass inetd_compatibility Hash init_groups TrueClass, FalseClass keep_alive TrueClass, FalseClass label String launch_only_once TrueClass, FalseClass limit_load_from_hosts Array limit_load_to_hosts Array limit_load_to_session_type String low_priority_io TrueClass, FalseClass mach_services Hash mode Integer, String nice Integer notifies # see description on_demand TrueClass, FalseClass owner Integer, String path String process_type String program String program_arguments Array provider Chef::Provider::Launchd queue_directories Array retries Integer retry_delay Integer root_directory String run_at_load TrueClass, FalseClass sockets Hash soft_resource_limits Array standard_error_path String standard_in_path String standard_out_path String start_calendar_interval Hash start_interval Integer start_on_mount TrueClass, FalseClass subscribes # see description throttle_interval Integer time_out Integer type String umask Integer username String wait_for_debugger TrueClass, FalseClass watch_paths Array working_directory String action Symbol # defaults to :create if not specified end
where
launchd
is the resourcename
is the name of the resource block:action
identifies the steps the chef-client will take to bring the node into the desired stateabandon_process_group
, backup
, cookbook
, debug
, disabled
, enable_globbing
, enable_transactions
, environment_variables
, exit_timeout
, group
, hard_resource_limits
, hash
, inetd_compatibility
, init_groups
, keep_alive
, label
, launch_only_once
, limit_load_from_hosts
, limit_load_to_hosts
, limit_load_to_session_type
, low_priority_io
, mach_services
, mode
, nice
, on_demand
, owner
, path
, process_type
, program
, program_arguments
, queue_directories
, retries
, retry_delay
, root_directory
, run_at_load
, sockets
, soft_resource_limits
, standard_error_path
, standard_in_path
, standard_out_path
, start_calendar_interval
, start_interval
, start_on_mount
, throttle_interval
, time_out
, type
, umask
, username
, wait_for_debugger
, watch_paths
, and working_directory
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:
:create
:create_if_missing
:delete
:disable
:enable
This resource has the following properties:
backup
Ruby Types: Integer, FalseClass
The number of backups to be kept in /var/chef/backup
. Set to false
to prevent backups from being kept.
cookbook
Ruby Type: String
The name of the cookbook in which the source files are located.
group
Ruby Types: String, Integer
When launchd is run as the root user, the group to run the job as. If the username
property is specified and this property is not, this value is set to the default group for the user.
hash
Ruby Type: Hash
A Hash of key value pairs used to create the launchd property list.
ignore_failure
Ruby Types: TrueClass, FalseClass
Continue running a recipe if a resource fails for any reason. Default value: false
.
label
Ruby Type: String
The unique identifier for the job.
mode
Ruby Types: Integer, String
A quoted 3-5 character string that defines the octal mode. For example: '755'
, '0755'
, or 00755
. If mode
is not specified and if the directory already exists, the existing mode on the directory is used. If mode
is not specified, the directory does not exist, and the :create
action is specified, the chef-client assumes a mask value of '0777'
, and then applies the umask for the system on which the directory is to be created to the mask
value. For example, if the umask on a system is '022'
, the chef-client uses the default value of '0755'
.
The behavior is different depending on the platform.
UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example: '755'
, '0755'
, or 00755
. If the value is specified as a quoted string, it works exactly as if the chmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use '0777'
or '777'
; for the same rights, plus the sticky bit, use 01777
or '1777'
.
Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example: '755'
, '0755'
, or 00755
. Values up to '0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where 4
equals GENERIC_READ
, 2
equals GENERIC_WRITE
, and 1
equals GENERIC_EXECUTE
. This property cannot be used to set :full_control
. This property has no effect if not specified, but when it and rights
are both specified, the effects are cumulative.
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
owner
Ruby Types: Integer, String
A string or ID that identifies the group owner by user name, including fully qualified user names such as domain\user
or user@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
Ruby Type: String
The path to the directory. Using a fully qualified path is recommended, but is not always required. Default value: the name
of the resource block See “Syntax” section above for more information.
provider
Ruby Type: Chef::Provider::Launchd
Optional. Explicitly specifies a provider. See “Providers” section below for more information.
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
.
session_type
Ruby Type: String
The type of launchd plist to be created. Possible values: system
(default) or user
.
source
Ruby Type: String
The path to the launchd property list.
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: Array
An array of options for supported mount features. Default value: { :remount => false }
.
type
Ruby Type: String
The type of resource. Possible values: daemon
(default), agent
.
The following resource properties may be used to define keys in the XML property list for a daemon or agent. Please refer to the Apple man page documentation for launchd for more information about these keys:
abandon_process_group
Ruby Types: TrueClass, FalseClass
If a job dies, all remaining processes with the same process ID may be kept running. Set to true
to kill all remaining processes.
debug
Ruby Types: TrueClass, FalseClass
Sets the log mask to LOG_DEBUG
for this job.
disabled
Ruby Types: TrueClass, FalseClass
Hints to launchctl
to not submit this job to launchd. Default value: false
.
enable_globbing
Ruby Types: TrueClass, FalseClass
Update program arguments before invocation.
enable_transactions
Ruby Types: TrueClass, FalseClass
Track in-progress transactions; if none, then send the SIGKILL
signal.
environment_variables
Ruby Type: Hash
Additional environment variables to set before running a job.
exit_timeout
Ruby Type: Integer
The amount of time (in seconds) launchd waits before sending a SIGKILL
signal. Default value: 20
.
hard_resource_limits
Ruby Type: Hash
A Hash of resource limits to be imposed on a job.
inetd_compatibility
Ruby Type: Hash
Specifies if a daemon expects to be run as if it were launched from inetd
. Set to wait => true
to pass standard input, output, and error file descriptors. Set to wait => false
to call the accept
system call on behalf of the job, and then pass standard input, output, and error file descriptors.
init_groups
Ruby Types: TrueClass, FalseClass
Specify if initgroups
is called before running a job. Default value: true
(starting with Mac OS X 10.5).
keep_alive
Ruby Types: TrueClass, FalseClass, Hash
Keep a job running continuously (true
) or allow demand and conditions on the node to determine if the job keeps running (false
). Default value: false
.
Hash type was added in Chef client 12.14.
launch_only_once
Ruby Types: TrueClass, FalseClass
Specify if a job can be run only one time. Set this value to true
if a job cannot be restarted without a full machine reboot.
limit_load_from_hosts
Ruby Type: Array
An array of hosts to which this configuration file does not apply, i.e. “apply this configuration file to all hosts not specified in this array”.
limit_load_to_hosts
Ruby Type: Array
An array of hosts to which this configuration file applies.
limit_load_to_session_type
Ruby Type: String
The session type to which this configuration file applies.
low_priority_io
Ruby Types: TrueClass, FalseClass
Specify if the kernel on the node should consider this daemon to be low priority during file system I/O.
mach_services
Ruby Type: Hash
Specify services to be registered with the bootstrap subsystem.
nice
Ruby Type: Integer
The program scheduling priority value in the range -20
to 20
.
on_demand
Ruby Types: TrueClass, FalseClass
Keep a job alive. Only applies to Mac OS X version 10.4 (and earlier); use keep_alive
instead for newer versions.
process_type
Ruby Type: String
The intended purpose of the job: Adaptive
, Background
, Interactive
, or Standard
.
program
Ruby Type: String
The first argument of execvp
, typically the file name associated with the file to be executed. This value must be specified if program_arguments
is not specified, and vice-versa.
program_arguments
Ruby Type: Array
The second argument of execvp
. If program
is not specified, this property must be specified and will be handled as if it were the first argument.
queue_directories
Ruby Type: Array
An array of non-empty directories which, if any are modified, will cause a job to be started.
root_directory
Ruby Type: String
chroot
to this directory, and then run the job.
run_at_load
Ruby Types: TrueClass, FalseClass
Launch a job once (at the time it is loaded). Default value: false
.
sockets
Ruby Type: Hash
A Hash of on-demand sockets that notify launchd when a job should be run.
soft_resource_limits
Ruby Type: Array
A Hash of resource limits to be imposed on a job.
standard_error_path
Ruby Type: String
The file to which standard error (stderr
) is sent.
standard_in_path
Ruby Type: String
The file to which standard input (stdin
) is sent.
standard_out_path
Ruby Type: String
The file to which standard output (stdout
) is sent.
start_calendar_interval
Ruby Type: Hash
A Hash (similar to crontab
) that defines the calendar frequency at which a job is started. For example: { minute => "0", hour => "20", day => "*", weekday => "1-5", month => "*" }
will run a job at 8:00 PM every day, Monday through Friday, every month of the year.
start_interval
Ruby Type: Integer
The frequency (in seconds) at which a job is started.
start_on_mount
Ruby Types: TrueClass, FalseClass
Start a job every time a file system is mounted.
throttle_interval
Ruby Type: Integer
The frequency (in seconds) at which jobs are allowed to spawn. Default value: 10
.
time_out
Ruby Type: Integer
The amount of time (in seconds) a job may be idle before it times out. If no value is specified, the default timeout value for launchd will be used.
umask
Ruby Type: Integer
A decimal value to pass to umask
before running a job.
username
Ruby Type: String
When launchd is run as the root user, the user to run the job as.
wait_for_debugger
Ruby Types: TrueClass, FalseClass
Specify if launchd has a job wait for a debugger to attach before executing code.
watch_paths
Ruby Type: Array
An array of paths which, if any are modified, will cause a job to be started.
working_directory
Ruby Type: String
chdir
to this directory, and then run the job.
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.
Create a Launch Daemon from a cookbook file
launchd 'com.chef.every15' do source 'com.chef.every15.plist' end
Create a Launch Daemon using keys
launchd 'call.mom.weekly' do program '/Library/scripts/call_mom.sh' start_calendar_interval 'weekday' => 7, 'hourly' => 10 time_out 300 end
Remove a Launch Daemon
launchd 'com.chef.every15' do action :delete 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_launchd.html