Ресурс файла

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

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

Используйте ресурс 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
  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
Выполнять атомарные обновления файла на основе каждого ресурса. Установите в 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'; для тех же прав плюс бит сохранения — 01777 или '1777'.

Microsoft Windows: Цитированная строка из 3-5 символов, определяющая восьмеричный режим, который преобразуется в права для безопасности Microsoft Windows. Например: '755', '0755', или 00755. Разрешены значения до '0777' (без бита сохранения), и они означают то же самое в Microsoft Windows, что и в 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 если команда возвращает ненулевой код возврата.

Примечание

Блок — произвольный код 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

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

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

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

Атомарные обновления включены по умолчанию. Их можно управлять глобально с помощью параметра 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.

Эти разрешения являются кумулятивными. Если указано :write, то это включает :read . Если указано :full_control, то это включает как :write, так и :read.

(Для тех, кто знаком с API Microsoft Windows: :read соответствует GENERIC_READ; :write соответствует GENERIC_WRITE; :read_execute соответствует GENERIC_READ и GENERIC_EXECUTE; :modify соответствует GENERIC_WRITE, GENERIC_READ, GENERIC_EXECUTE, и DELETE; :full_control соответствует GENERIC_ALL, что позволяет пользователю изменять владельца и другую метаданные файла.)

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

Уведомления

notifies

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

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

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

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

:before: Указывает, что действие над уведомлённым ресурсом должно выполняться до обработки блока ресурса, в котором находится уведомление.
:delayed: По умолчанию. Указывает, что уведомление должно быть помещено в очередь и выполнено в конце выполнения клиента Chef Infra.
: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.
:immediate, :immediately: Указывает, что уведомление должно быть выполнено немедленно для каждого уведомлённого ресурса.

Синтаксис для subscribes:

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

Условия

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

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

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

Свойства

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

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/