file Ресурс

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

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

Используйте ресурс file для управления файлами непосредственно на узле.

Примечание

Используйте ресурс cookbook_file для копирования файла из каталога /files кулинарной книги. Используйте ресурс template для создания файла на основе шаблона в каталоге /templates кулинарной книги. Используйте ресурс remote_file для передачи файла на узел из удаленного расположения.

Синтаксис

Блок ресурса file управляет файлами, существующими на узлах. Например, чтобы записать главную страницу веб-сайта Apache:

file '/var/www/customers/public_html/index.php' do
  content '<html>This is a placeholder for the home page.</html>'
  mode '0755'
  owner 'web_admin'
  group 'web_admin'
end

где:

'/var/www/customers/public_html/index.php' — путь к файлу, а также имя файла, подлежащего управлению
content определяет содержимое файла

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

file 'name' do
  atomic_update              true, false
  backup                     false, Integer
  checksum                   String
  content                    String
  force_unlink               true, false
  group                      String, Integer
  inherits                   true, false
  manage_symlink_source      true, false
  mode                       String, Integer
  owner                      String, Integer
  path                       String # defaults to 'name' if not specified
  rights                     Hash
  verify                     String, Block, Symbol
  action                     Symbol # defaults to :create if not specified
end

где:

file — ресурс.
name — имя, присвоенное блоку ресурса.
action определяет действия Chef Infra Client для приведения узла в желаемое состояние.
atomic_update, backup, checksum, content, force_unlink, group, inherits, manage_symlink_source, mode, owner, path, rights, sensitive и verify — свойства этого ресурса с указанным типом Ruby. Более подробную информацию обо всех свойствах этого ресурса см. в разделе «Свойства».

Действия

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

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

Свойства

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

atomic_update: Тип Ruby: true, false | Значение по умолчанию: False if modifying /etc/hosts, /etc/hostname, or /etc/resolv.conf within Docker containers. Otherwise default to the client.rb 'file_atomic_update' config value.
Выполнять атомарные обновления файла на основе каждого ресурса. Установить в значение true для атомарных обновлений. Установить в значение false для неатомарных обновлений. Это значение переопределяет file_atomic_update, которое является глобальным значением, определенным в файле client.rb.

backup: Тип Ruby: Целое число, false | Значение по умолчанию: 5
Количество резервных копий, которые необходимо сохранить в /var/chef/backup (для платформ на основе UNIX и Linux) или C:/chef/backup (для платформы Microsoft Windows). Установить в false, чтобы предотвратить сохранение резервных копий.

checksum: Тип Ruby: Строка
Сумма проверки SHA-256 файла. Используется для обеспечения того, что используется определенный файл. Если сумма проверки не совпадает, файл не используется.

content: Тип Ruby: Строка
Строка, которая записывается в файл. Содержимое этого свойства заменяет предыдущее содержимое, когда это свойство имеет значение, отличное от значения по умолчанию. По умолчанию содержимое не изменяется.

force_unlink: Тип Ruby: true, false | Значение по умолчанию: false
Как Chef Infra Client обрабатывает определенные ситуации, когда целевой файл оказывается не файлом. Например, когда целевой файл — это фактически символическая ссылка. Установите в значение true, чтобы Chef Infra Client удалил целевой не-файл и заменил его указанным файлом. Установите в значение false, чтобы Chef Infra Client выдал ошибку.

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

inherits: Тип Ruby: true, false | Значение по умолчанию: true
Только Microsoft Windows. Наследует ли файл права из родительского каталога.

manage_symlink_source

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

(с предупреждением)

Изменение поведения ресурса файла, если он указывает на символическую ссылку. Когда это значение установлено в false, Chef Infra Client будет управлять правами символической ссылки или заменит символическую ссылку обычным файлом, если у ресурса есть содержимое. Когда это значение установлено в true, Chef будет следовать символической ссылке и будет управлять правами и содержимым целевого файла символической ссылки.

Поведение по умолчанию — true, но выводится предупреждение, что значение по умолчанию будет изменено на false в будущей версии; явное указание этого значения на true или false подавляет это предупреждение.

mode

Тип Ruby: Целое число, Строка

Процитированная строка из 3-5 символов, определяющая восьмеричный режим. Например: '755', '0755' или 00755. Если mode не указано и если файл уже существует, используется существующий режим файла. Если mode не указано, файл не существует и указано действие :create, Chef Infra Client предполагает значение маски '0777', а затем применяет маску umask для системы, на которой должен быть создан файл, к значению mask. Например, если umask в системе — '022', Chef Infra Client использует значение по умолчанию '0755'.

Поведение отличается в зависимости от платформы.

Системы на основе UNIX и Linux: Процитированная строка из 3-5 символов, определяющая восьмеричный режим, который передается в chmod. Например: '755', '0755' или 00755. Если значение указано в виде процитированной строки, оно работает точно так же, как если бы была передана команда chmod. Если значение указано как целое число, добавьте ноль (0) к значению, чтобы убедиться, что оно интерпретируется как восьмеричное число. Например, для назначения прав чтения, записи и выполнения для всех пользователей используйте '0777' или '777'; для тех же прав плюс бит «sticky» используйте 01777 или '1777'.

Microsoft Windows: Процитированная строка из 3-5 символов, определяющая восьмеричный режим, который преобразуется в права безопасности для Microsoft Windows. Например: '755', '0755' или 00755. Разрешены значения до '0777' (без битов «sticky») и означают то же, что и в UNIX, где 4 равно GENERIC_READ, 2 равно GENERIC_WRITE и 1 равно GENERIC_EXECUTE. Это свойство не может использоваться для установки :full_control. Это свойство не имеет эффекта, если не указано, но когда оно и rights указаны оба, эффекты суммируются.

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

path

Тип Ruby: Строка

Полный путь к файлу, включая имя файла и его расширение. Например: /files/file.txt. Значение по умолчанию: name блока ресурса. Дополнительную информацию см. в разделе «Синтаксис» выше.

Microsoft Windows: Путь, начинающийся с косой черты (/), будет указывать на корень текущего рабочего каталога процесса Chef Infra Client. Этот путь может различаться в разных системах. Поэтому использование пути, начинающегося с косой черты (/), не рекомендуется.

rights: Тип Ruby: Целое число, Строка
Только Microsoft Windows. Права пользователей и групп в среде Microsoft Windows. Например: rights <permissions>, <principal>, <options>, где <permissions> определяет права, предоставленные субъекту, <principal> — имя группы или пользователя, а <options> — словарь с одним (или несколькими) расширенными вариантами прав.

verify

Тип Ruby: Строка, Блок, Символ

Позволяет проверить содержимое файла перед его созданием. Создаёт временный файл и затем позволяет выполнить команды или код Ruby. Если этот код вернёт true, файл будет создан. Если код вернёт false, будет выброшено исключение.

Типы этого свойства — блок, строка или символ. При указании блока он возвращает true или false. При указании строки она выполняется как системная команда. Возвращает true, если команда возвращает 0 в качестве кода возврата, и false, если команда возвращает код возврата, отличный от нуля. При использовании встроенного символа верификатора он возвращает true, если верификатор успешно прошёл, иначе — false. В настоящее время поддерживаются верификаторы :yaml, :json и :systemd_unit.

Примечание

Блок — произвольный код Ruby, определённый внутри блока ресурса с помощью свойства verify. Когда блок возвращает true, Chef Infra Client продолжит обновлять файл как необходимо.

Например, это должно вернуть true:

file '/tmp/baz'  do
  verify { 1 == 1 }
end

Это также должно вернуть true:

file '/etc/nginx.conf' do
  verify 'nginx -t -c %{path}'
end

В этом примере часть %{path} этой команды расширяется до временного расположения, где существует копия создаваемого файла. Это будет использовать функцию проверки синтаксиса Nginx, чтобы убедиться, что файл является допустимым конфигурационным файлом Nginx, прежде чем записать файл. Если выполненная команда возвращает код возврата, отличный от нуля, будет выброшено исключение.

Это должно вернуть true:

file '/tmp/foo' do
  content "hello"
  verify do |path|
    open(path).read.include?       "hello"
  end
end

В то время как это должно вернуть false:

file '/tmp/foo' do
  content "goodbye"
  verify do |path|
    open(path).read.include?       "hello"
  end
end

При использовании одного из встроенных символов (:json, :yaml, :systemd_unit) Это должно вернуть true:

file 'foo.json' do
  content '{"foo": "bar"}'
  verify :json
end

В то время как это должно вернуть false:

file 'foo.yaml' do
    content "--- foo: 'foo-"
    verify :yaml
end

Если строка, блок или символ возвращают false, выполнение Chef Infra Client остановится и будет выброшено исключение.

Атомарные обновления файлов

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

Атомарные обновления включены по умолчанию. Их можно настроить глобально с помощью настройки file_atomic_update в файле client.rb. Их можно настроить на уровне каждого ресурса с помощью свойства atomic_update, доступного для ресурсов cookbook_file, file, remote_file и template.

Примечание

На некоторых платформах после перемещения файла Chef Infra Client может изменить права доступа к файлу, чтобы поддержать функции, специфичные для этих платформ. На платформах с включённым SELinux Chef Infra Client исправит контексты безопасности после перемещения файла в правильное место, выполнив команду restorecon. На платформе Microsoft Windows Chef Infra Client создаст файлы так, чтобы наследование ACL работало как ожидается.

Безопасность файлов в Windows

Для поддержки безопасности Microsoft Windows ресурсы template, file, remote_file, cookbook_file, directory и remote_directory поддерживают использование наследования и списков управления доступом (ACL) внутри рецептов. Списки управления доступом (ACL)

Свойство rights может использоваться в рецепте для управления списками управления доступом (ACL), которые позволяют предоставлять разрешения нескольким пользователям и группам. Свойство rights может использоваться любое количество раз; Chef Infra Client применит их к файлу или каталогу по мере необходимости. Синтаксис свойства rights следующий:

rights permission, principal, option_type => value

где

permission: Используется для указания прав, предоставляемых principal. Возможные значения: :read, :write, read_execute, :modify, :full_control или целое число.; Целые числа, используемые для прав, должны соответствовать следующему списку список перечисления FileSystemRights.

These permissions are cumulative. If `:write` is specified, then it
includes `:read`. If `:full_control` is specified, then it includes
both `:write` and `:read`.

(For those who know the Microsoft Windows API: `:read` corresponds
to `GENERIC_READ`; `:write` corresponds to `GENERIC_WRITE`;
`:read_execute` corresponds to `GENERIC_READ` and `GENERIC_EXECUTE`;
`:modify` corresponds to `GENERIC_WRITE`, `GENERIC_READ`,
`GENERIC_EXECUTE`, and `DELETE`; `:full_control` corresponds to
`GENERIC_ALL`, which allows a user to change the owner and other
metadata about a file.)

principal

Используется для указания группы или пользователя. Субъект может быть указан по имени или SID. При использовании имени это идентично тому, что вводится в поле входа для Microsoft Windows, например, user_name, domain\user_name или user_name@fully_qualified_domain_name. При использовании SID можно использовать стандартное строковое представление SID (S-R-I-S-S) или один из постоянных строк SDDL. Chef Infra Client не нужно знать, является ли субъект пользователем или группой.

option_type

Хеш, содержащий расширенные параметры прав. Например, права каталога, которые применяются только к первому уровню дочерних элементов, могут выглядеть так: rights :write, 'domain\group_name', :one_level_deep => true. Возможные типы опций:

Тип опции	Описание
`:applies_to_children`	Указывает, как разрешения применяются к дочерним элементам. Возможные значения: `true` для наследования как дочерних каталогов, так и файлов; `false` для отказа от наследования любых дочерних каталогов или файлов; `:containers_only` для наследования только дочерних каталогов (а не файлов); `:objects_only` для рекурсивного наследования файлов (а не дочерних каталогов).
`:applies_to_self`	Указывает, применяется ли разрешение к родительскому каталогу. Возможные значения: `true` для применения к родительскому каталогу или файлу и его дочерним элементам; `false` для применения только к дочерним каталогам и файлам.
`:one_level_deep`	Указывает глубину, до которой будут применяться разрешения. Возможные значения: `true` для применения только к первому уровню дочерних элементов; `false` для применения ко всем дочерним элементам.

Например:

resource 'x.txt' do
  rights :read, 'S-1-1-0'
  rights :write, 'domain\group'
  rights :full_control, 'group_name_or_user_name'
  rights :full_control, 'user_name', applies_to_children: true
end

или:

rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true

Некоторые другие важные моменты при использовании атрибута rights:

Остаются только унаследованные права. Все существующие явные права на объект удаляются и заменяются.
Если права не указаны, ничего не изменится. Chef Infra Client не очищает права на файл или каталог, если права не указаны.
Изменение унаследованных прав может быть дорогостоящим. Microsoft Windows будет рекурсивно распространять права на все дочерние элементы из-за наследования. Это нормальная особенность Microsoft Windows, поэтому рассмотрите частоту, с которой требуется этот тип действия, и предпримите шаги для контроля этого типа действий, если производительность является главным фактором.

Используйте свойство deny_rights, чтобы запретить определённые права определённым пользователям. Порядок не зависит от использования свойства rights. Например, не имеет значения, помещены ли права для всех перед или после deny_rights :read, ['Julian', 'Lewis'], и Джулиан, и Левис не смогут читать документ. Например:

resource 'x.txt' do
  rights :read, 'Everyone'
  rights :write, 'domain\group'
  rights :full_control, 'group_name_or_user_name'
  rights :full_control, 'user_name', applies_to_children: true
  deny_rights :read, %w(Julian Lewis)
end

или:

deny_rights :full_control, ['Sally']

Наследование

По умолчанию файл или каталог наследует права от родительского каталога. В большинстве случаев это предпочтительное поведение, но иногда может потребоваться принять меры для более конкретного контроля прав. Свойство inherits может использоваться для указания Chef Infra Client на применение (или отказ от применения) унаследованных прав от родительского каталога.

Например, в следующем примере указаны права для каталога:

directory 'C:\mordor' do
  rights :read, 'MORDOR\Minions'
  rights :full_control, 'MORDOR\Sauron'
end

а затем в следующем примере показано, как использовать наследование для запрета доступа к дочернему каталогу:

directory 'C:\mordor\mount_doom' do
  rights :full_control, 'MORDOR\Sauron'
  inherits false # Sauron is the only person who should have any sort of access
end

Если использовать право deny_rights, что-то может проскользнуть, если не запретить все пользователи и группы.

Ещё один пример показывает, как указать права для каталога:

directory 'C:\mordor' do
  rights :read, 'MORDOR\Minions'
  rights :full_control, 'MORDOR\Sauron'
  rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end

но затем не использовать свойство inherits, чтобы запретить эти права в дочернем каталоге:

directory 'C:\mordor\mount_doom' do
  deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end

Поскольку свойство inherits не указано, Chef Infra Client по умолчанию установит его в значение true, что гарантирует, что настройки безопасности существующих файлов останутся неизменными.

Общие функциональные возможности ресурсов

Ресурсы 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, которые сгенерируют ошибку, если другой ресурс не существует.

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

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

Примеры

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

Создание файла

file '/tmp/something' do
  owner 'root'
  group 'root'
  mode '0755'
  action :create
end

Создание файла в Microsoft Windows

Чтобы создать файл в Microsoft Windows, убедитесь, что вы добавили символ экранирования — \ — перед обратными слешами в путях:

file 'C:\\tmp\\something.txt' do
  rights :read, 'Everyone'
  rights :full_control, 'DOMAIN\\User'
  action :create
end

Удаление файла

file '/tmp/something' do
  action :delete
end

Установка режимов файла

file '/tmp/something' do
  mode '0755'
end

Удаление репозитория с помощью yum для очистки кэша

# the following code sample thanks to gaffneyc @ https://gist.github.com/918711

execute 'clean-yum-cache' do
  command 'yum clean all'
  action :nothing
end

file '/etc/yum.repos.d/bad.repo' do
  action :delete
  notifies :run, 'execute[clean-yum-cache]', :immediately
  notifies :create, 'ruby_block[reload-internal-yum-cache]', :immediately
end

Добавление значения элемента хранилища данных в файл

Следующий пример показывает, как получить содержимое элемента хранилища данных под именем impossible_things, создать файл .pem по адресу some/directory/path/, а затем использовать атрибут content для обновления содержимого этого файла значением элемента хранилища данных impossible_things:

private_key = data_bag_item('impossible_things', private_key_name)['private_key']

file "some/directory/path/#{private_key_name}.pem" do
  content private_key
  owner 'root'
  group 'group'
  mode '0755'
end

Запись файла YAML

Следующий пример демонстрирует использование свойства content для записи файла YAML:

file "#{app['deploy_to']}/shared/config/settings.yml" do
  owner "app['owner']"
  group "app['group']"
  mode '0755'
  content app.to_yaml
end

Запись строки в файл

Следующий пример задаёт каталог и использует свойство content для добавления строки в файл, созданный в этом каталоге:

status_file = '/path/to/file/status_file'

file status_file do
  owner 'root'
  group 'root'
  mode '0755'
  content 'My favourite foremost coastal Antarctic shelf, oh Larsen B!'
end

Создание файла из копии

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

file '/root/1.txt' do
  content IO.read('/tmp/1.txt')
  action :create
end

где атрибут content использует метод Ruby IO.read для получения содержимого файла /tmp/1.txt.

© 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/file/