Ресурс launchd

Эта страница сгенерирована из исходного кода клиента Chef Infra. Чтобы предложить изменение, отредактируйте файл launchd.rb и отправьте запрос на вытягивание в репозиторий Chef Infra Client.

Все страницы ресурсов Infra

Используйте ресурс launchd для управления системными службами (демонами) и службами для каждого пользователя (агентами) на платформе macOS.

Новинка в Chef Infra Client 12.8.

Синтаксис

Полный синтаксис всех доступных свойств ресурса launchd:

launchd 'name' do
  abandon_process_group           true, false
  backup                          Integer, false
  cookbook                        String
  debug                           true, false
  disabled                        true, false # default value: false
  enable_globbing                 true, false
  enable_transactions             true, false
  environment_variables           Hash
  exit_timeout                    Integer
  group                           String, Integer
  hard_resource_limits            Hash
  inetd_compatibility             Hash
  init_groups                     true, false
  keep_alive                      true, false, Hash
  label                           String # default value: 'name' unless specified
  launch_events                   Hash
  launch_only_once                true, false
  ld_group                        String
  limit_load_from_hosts           Array
  limit_load_to_hosts             Array
  limit_load_to_session_type      Array, String
  low_priority_io                 true, false
  mach_services                   Hash
  mode                            String, Integer
  nice                            Integer
  on_demand                       true, false
  owner                           String, Integer
  path                            String
  plist_hash                      Hash
  process_type                    String
  program                         String
  program_arguments               Array
  queue_directories               Array
  root_directory                  String
  run_at_load                     true, false
  session_type                    String
  sockets                         Hash
  soft_resource_limits            Array
  source                          String
  standard_error_path             String
  standard_in_path                String
  standard_out_path               String
  start_calendar_interval         Hash, Array
  start_interval                  Integer
  start_on_mount                  true, false
  throttle_interval               Integer
  time_out                        Integer
  type                            String # default value: "daemon"
  username                        String
  wait_for_debugger               true, false
  watch_paths                     Array
  working_directory               String
  action                          Symbol # defaults to :create if not specified
end

где:

launchd — это ресурс.
name — имя блока ресурса.
action определяет, какие шаги предпримет Chef Infra Client, чтобы привести узел в нужное состояние.
abandon_process_group, backup, cookbook, debug, disabled, enable_globbing, enable_transactions, environment_variables, exit_timeout, group, hard_resource_limits, inetd_compatibility, init_groups, keep_alive, label, launch_events, launch_only_once, ld_group, limit_load_from_hosts, limit_load_to_hosts, limit_load_to_session_type, low_priority_io, mach_services, mode, nice, on_demand, owner, path, plist_hash, process_type, program, program_arguments, queue_directories, root_directory, run_at_load, session_type, sockets, soft_resource_limits, source, standard_error_path, standard_in_path, standard_out_path, start_calendar_interval, start_interval, start_on_mount, throttle_interval, time_out, type, username, wait_for_debugger, watch_paths, и working_directory — доступные свойства этого ресурса.

Действия

Ресурс launchd имеет следующие действия:

:create: Создать список свойств launchd. (по умолчанию)
:create_if_missing: Создать список свойств launchd, если он еще не существует.
:delete: Удалить список свойств launchd. Это приведет к разгрузке демона или агента, если они загружены.
:disable: Отключить список свойств launchd.
:enable: Создать список свойств launchd и затем убедиться, что он включен. Если список свойств launchd уже существует, но не соответствует требованиям, обновить список свойств для соответствия и перезапустить демон или агента.
:nothing: Этот блок ресурса не действует, пока другой ресурс не сообщит ему о необходимости принять действие. После получения уведомления этот блок ресурса либо выполняется немедленно, либо добавляется в очередь для выполнения в конце выполнения Chef Infra Client.
:restart: Перезапустить демон или агента, управляемые launchd.

Свойства

Ресурс launchd имеет следующие свойства:

abandon_process_group: Тип Ruby: true, false
Если задача завершается аварийно, все оставшиеся процессы с тем же идентификатором процесса могут продолжать работать. Установите значение true, чтобы завершить все оставшиеся процессы.

backup: Тип Ruby: Целое число, false
Количество резервных копий, которые необходимо сохранить в /var/chef/backup. Установите значение false, чтобы предотвратить сохранение резервных копий.

cookbook: Тип Ruby: Строка
Имя кулинарии, в которой находятся исходные файлы.

group: Тип Ruby: Строка, Целое число
Группа, в которой будет выполняться задача, когда launchd выполняется как пользователь root. Если свойство username указано, а это свойство нет, его значение устанавливается по умолчанию для группы пользователя.

label: Тип Ruby: Строка
Уникальный идентификатор задачи.

mode: Тип Ruby: Целое число, строка | Значение по умолчанию: '0755'
Приведенная в кавычки строка из 3-5 символов, определяющая восьмеричный режим. Например: '755', '0755', или 00755.

owner: Тип Ruby: Целое число, строка
Строка или идентификатор, определяющий владельца группы по имени пользователя, включая полные имена пользователей, такие как domain\user или user@domain. Если это значение не указано, существующие владельцы остаются неизменными, а новые назначения владельцев используют текущего пользователя (при необходимости).

path: Тип Ruby: Строка
Путь к каталогу. Рекомендуется использовать полностью квалифицированный путь, но это не всегда обязательно. Значение по умолчанию: name блока ресурса. См. раздел «Синтаксис» выше для получения дополнительной информации.

plist_hash: Тип Ruby: Хэш
Хэш пар ключ-значение, используемый для создания списка свойств launchd.

session_type: Тип Ruby: Строка
Тип создаваемого списка свойств launchd. Возможные значения: system (по умолчанию) или user.

source: Тип Ruby: Строка
Путь к списку свойств launchd.

type: Тип Ruby: Строка
Тип ресурса. Возможные значения: daemon (по умолчанию), agent.

abandon_process_group: Тип Ruby: true, false
Если задача завершается аварийно, все оставшиеся процессы с тем же идентификатором процесса могут продолжать работать. Установите значение true, чтобы завершить все оставшиеся процессы.

debug: Тип Ruby: true, false
Устанавливает маску журнала на LOG_DEBUG для этой задачи.

disabled: Тип Ruby: true, false | Значение по умолчанию: false
Подсказки launchctl для того, чтобы не отправлять эту задачу в launchd.

enable_globbing: Тип Ruby: true, false
Обновить аргументы программы перед вызовом.

enable_transactions: Тип Ruby: true, false
Отслеживать транзакции в процессе; если нет, отправлять сигнал SIGKILL.

environment_variables: Тип Ruby: Хэш
Дополнительные переменные окружения, которые необходимо установить перед запуском задачи.

exit_timeout: Тип Ruby: Целое число
Время (в секундах), которое launchd ожидает перед отправкой сигнала SIGKILL.

hard_resource_limits: Тип Ruby: Хэш
Хэш ограничений ресурсов, которые необходимо наложить на задачу.

inetd_compatibility: Тип Ruby: Хэш
Указывает, ожидает ли демон запуска как будто он запущен из inetd. Установите wait => true, чтобы передать стандартные дескрипторы файлов ввода, вывода и ошибки. Установите wait => false, чтобы вызвать системный вызов accept от имени задачи, а затем передать стандартные дескрипторы файлов ввода, вывода и ошибки.

init_groups: Тип Ruby: true, false
Указать, вызывается ли initgroups перед запуском задачи.

keep_alive

Тип Ruby: true, false, Хэш

Поддерживать задачу в непрерывном режиме (true) или позволять потребностям и условиям на узле определять, сохраняется ли запуск задачи (false).

Новое в Chef Client 12.14

launch_events

Тип Ruby: Хэш

Укажите типы событий более высокого уровня, которые будут использоваться в качестве источников событий запуска по требованию.

Новое в Chef Infra Client 15.1

launch_only_once: Тип Ruby: true, false
Указать, может ли задача выполняться только один раз. Установите это значение в true, если задачу нельзя перезапустить без полного перезапуска машины.

limit_load_from_hosts: Тип Ruby: Массив
Массив хостов, к которым этот конфигурационный файл не применяется, т.е. «применить этот конфигурационный файл ко всем хостам, не указанным в этом массиве».

limit_load_to_hosts: Тип Ruby: Массив
Массив хостов, к которым применяется этот конфигурационный файл.

limit_load_to_session_type: Тип Ruby: Массив, Строка
Тип(ы) сеанса, к которому применяется этот конфигурационный файл.

low_priority_io: Тип Ruby: true, false
Указать, должен ли ядро на узле рассматривать этот демон как низкий приоритет во время ввода-вывода файловой системы.

mach_services: Тип Ruby: Хэш
Укажите службы, которые необходимо зарегистрировать в подсистеме загрузки.

nice: Тип Ruby: Целое число
Значение приоритета планирования программы в диапазоне от -20 до 19.

on_demand: Тип Ruby: true, false
Удерживать задачу активной. Применимо только к версии macOS 10.4 (и более ранним); используйте keep_alive для более новых версий.

process_type: Тип Ruby: Строка
Предполагаемое назначение задачи: Adaptive, Background, Interactive, или Standard.

program: Тип Ruby: Строка
Первый аргумент execvp, обычно имя файла, связанное с файлом, который должен быть выполнен. Это значение должно быть указано, если program_arguments не указано, и наоборот.

program_arguments: Тип Ruby: Массив
Второй аргумент execvp. Если программа не указана, этот параметр должен быть указан и будет обработан так, как если бы это был первый аргумент.

queue_directories: Тип Ruby: Массив
Массив непустых каталогов, изменение которых вызовет запуск задачи.

root_directory: Тип Ruby: Строка
chroot в этот каталог, а затем запустить задачу.

run_at_load: Тип Ruby: true, false
Запустить задачу один раз (в момент загрузки).

sockets: Тип Ruby: Хэш
Хэш сокетов по требованию, уведомляющих launchd о необходимости запуска задачи.

soft_resource_limits: Тип Ruby: Массив
Хэш ограничений ресурсов, которые нужно наложить на задачу.

standard_error_path: Тип Ruby: Строка
Файл, в который отправляется стандартная ошибка (stderr).

standard_in_path: Тип Ruby: Строка
Файл, в который отправляется стандартный ввод (stdin).

standard_out_path: Тип Ruby: Строка
Файл, в который отправляется стандартный вывод (stdout).

start_calendar_interval: Тип Ruby: Хэш
Хэш (аналогичный crontab), определяющий частоту запуска задачи по календарю. Например: { Minute => "0", Hour => "20", Day => "*", Weekday => "1-5", Month => "*" } будет запускать задачу в 20:00 каждый день, с понедельника по пятницу, каждый месяц в году.

start_interval: Тип Ruby: Целое число
Частота (в секундах) запуска задачи.

start_on_mount: Тип Ruby: true, false
Запускать задачу каждый раз при подключении файловой системы.

throttle_interval: Тип Ruby: Целое число | Значение по умолчанию: 10
Частота (в секундах), с которой задачи разрешается запускать.

time_out: Тип Ruby: Целое число
Время (в секундах), которое задача может простаивать перед истечением времени ожидания. Если значение не указано, будет использовано значение по умолчанию для launchd.

username: Тип Ruby: Строка
При запуске launchd от пользователя root, пользователь, от имени которого будет запускаться задача.

wait_for_debugger: Тип Ruby: true, false
Указывает, ожидает ли launchd привязки отладчика к задаче перед выполнением кода.

watch_paths: Тип Ruby: Массив
Массив путей, изменение которых вызовет запуск задачи.

working_directory: Тип Ruby: Строка
Переход в этот каталог, а затем запуск задачи.

Общие возможности ресурсов

Ресурсы Chef включают общие свойства, уведомления и защитные механизмы ресурсов.

Общие свойства

Следующие свойства являются общими для каждого ресурса:

compile_time

Тип Ruby: true, false | Значение по умолчанию: false

Управление фазой, в которой ресурс выполняется на узле. Установите в true, чтобы выполнить его во время создания коллекции ресурсов (compile phase). Установите в false, чтобы выполнить его во время настройки узла Chef Infra Client (converge phase).

ignore_failure

Тип Ruby: true, false, :quiet | Значение по умолчанию: false

Продолжить выполнение рецепта, если ресурс потерпит неудачу по какой-либо причине. :quiet не будет отображать полный стек вызовов, и рецепт продолжится, если ресурс потерпит неудачу.

retries

Тип Ruby: Целое число | Значение по умолчанию: 0

Количество попыток перехватить исключения и повторить ресурс.

retry_delay

Тип Ruby: Целое число | Значение по умолчанию: 2

Задержка в секундах между попытками повтора.

sensitive

Тип Ruby: true, false | Значение по умолчанию: false

Обеспечить, чтобы конфиденциальные данные ресурса не регистрировались Chef Infra Client.

Уведомления

notifies

Тип Ruby: Символ, 'Chef::Resource[Строка]'

Ресурс может уведомить другой ресурс о действиях при изменении его состояния. Укажите 'resource[name]', :action (действие, которое должен выполнить ресурс), а затем :timer для этого действия. Ресурс может уведомлять несколько ресурсов; используйте оператор notifies для каждого уведомляемого ресурса.

Если ссылаемый ресурс не существует, возникает ошибка. В отличие от subscribes, который не завершит выполнение, если исходный ресурс не найден.

Таймер определяет момент во время выполнения Chef Infra Client, когда выполняется уведомление. Доступны следующие таймеры:

:before: Указывает, что действие над уведомленным ресурсом должно выполняться до обработки блока ресурса, в котором расположено уведомление.
:delayed: По умолчанию. Указывает, что уведомление должно быть помещено в очередь и выполнено в конце выполнения Chef Infra Client.
:immediate, :immediately: Указывает, что уведомление должно выполняться немедленно для каждого уведомленного ресурса.

Синтаксис notifies:

notifies :action, 'resource[name]', :timer

subscribes: Тип Ruby: Символ, 'Chef::Resource[Строка]'

Ресурс может прослушивать другой ресурс и выполнять действия, если состояние прослушиваемого ресурса изменится. Укажите 'resource[name]', :action (действие), а затем :timer для этого действия.

Обратите внимание, что subscribes не применяет указанное действие к ресурсу, который он прослушивает - например:

file '/etc/nginx/ssl/example.crt' do
  mode '0600'
  owner 'root'
end

service 'nginx' do
  subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end

В этом случае свойство subscribes перезагружает сервис nginx всякий раз, когда файл его сертификата, расположенный в /etc/nginx/ssl/example.crt, обновляется. subscribes не вносит никаких изменений в сам файл сертификата, а только прослушивает изменения файла и выполняет действие :reload для своего ресурса (в данном примере nginx) при обнаружении изменений.

Если другой ресурс не существует, подписка не приведет к ошибке. В отличие от более жесткой семантики notifies, которая вызовет ошибку, если другой ресурс не существует.

:before: Указывает, что действие над уведомленным ресурсом должно выполняться до обработки блока ресурса, в котором расположено уведомление.
:delayed: По умолчанию. Указывает, что уведомление должно быть помещено в очередь и выполнено в конце выполнения Chef Infra Client.
:immediate, :immediately: Указывает, что уведомление должно выполняться немедленно для каждого уведомленного ресурса.

Синтаксис subscribes:

subscribes :action, 'resource[name]', :timer

Защитные механизмы

Свойство защитного механизма может использоваться для оценки состояния узла во время фазы выполнения Chef Infra Client. Основываясь на результатах этой оценки, защитное свойство используется для указания Chef Infra Client, следует ли продолжить выполнение ресурса. Свойство защитного механизма принимает строковое значение или значение Ruby-блока:

Строка выполняется как команда оболочки. Если команда возвращает 0, защитный механизм применяется. Если команда возвращает любое другое значение, то свойство защитного механизма не применяется. Строковые защитные механизмы в powershell_script запускают команды Windows PowerShell и могут возвращать true помимо 0.
Блок выполняется как код Ruby, который должен возвращать либо true, либо false. Если блок возвращает true, защитный механизм применяется. Если блок возвращает false, защитный механизм не применяется.

Свойство защитного механизма полезно для обеспечения идемпотентности ресурса, позволяя этому ресурсу проверять требуемое состояние по мере его выполнения, а затем, если требуемое состояние присутствует, ничего не делать Chef Infra Client.

Свойства

Следующие свойства могут использоваться для определения защитного механизма, который оценивается во время фазы выполнения Chef Infra Client:

not_if: Предотвращает выполнение ресурса, когда условие возвращает true.
only_if: Разрешает выполнение ресурса только в том случае, если условие возвращает true.

Примеры

Следующие примеры демонстрируют различные подходы к использованию ресурса launchd в рецептах:

Создание Launch Daemon из файла кулинарной книги

launchd 'com.chef.every15' do
  source 'com.chef.every15.plist'
end

Создание Launch Daemon с использованием ключей

launchd 'call.mom.weekly' do
  program '/Library/scripts/call_mom.sh'
  start_calendar_interval 'Weekday' => 7, 'Hourly' => 10
  time_out 300
end

Удаление 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.chef.io/resources/launchd/