Ресурс launchd

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

Страница справочника по ресурсам

Используйте ресурс 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"
  umask                           Integer
  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, umask, 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: Integer, false
Количество резервных копий, которые необходимо хранить в /var/chef/backup. Установите значение false, чтобы предотвратить сохранение резервных копий.

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

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

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

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

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

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

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

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

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

type: Тип Ruby: String
Тип ресурса. Возможные значения: 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: Hash
Дополнительные переменные среды, которые необходимо установить перед запуском задачи.

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

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

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

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

keep_alive

Тип Ruby: true, false, Hash

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

Новое в Chef Client 12.14

launch_events

Тип Ruby: Hash

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

Новое в Chef Infra Client 15.1

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

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

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

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

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

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

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

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

process_type: Тип Ruby: String
Предназначение задачи: Adaptive, Background, Interactive или Standard.

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

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

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

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

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

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

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

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

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

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

start_calendar_interval: Тип Ruby: Hash
Хэш (аналогичный 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.

umask: Тип Ruby: Целое число
Десятичное значение для передачи umask перед запуском задачи.

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

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

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

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

Общие функции ресурсов

Ресурсы 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 InfraClient.

Уведомления

notifies

Тип Ruby: Символ, 'Chef::Resource[String]'

Ресурс может уведомить другой ресурс о выполнении действия при изменении его состояния. Укажите '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[String]'

Ресурс может прослушивать другой ресурс и выполнять действие, если состояние прослушиваемого ресурса меняется. Укажите '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 в рецептах:

Создание демона запуска из файла кулинарной книги

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

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

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

Удаление демона запуска

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/