remote_file Ресурс

Редактировать эту страницу в репозитории Chef

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

Используйте ресурс remote_file для передачи файла из удаленного местоположения с использованием спецификации файла. Этот ресурс похож на ресурс file.

Синтаксис

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

remote_file '/var/www/customers/public_html/index.html' do
  source 'http://somesite.com/index.html'
  owner 'web_admin'
  group 'web_admin'
  mode '0755'
  action :create
end

где:

• '/var/www/customers/public_html/index.html' — путь к файлу, который необходимо создать
• 'http://somesite.com/index.html' указывает местоположение удаленного файла, файл загружается оттуда
• owner, group и mode определяют права доступа

Полный синтаксис для всех свойств, доступных ресурсу remote_file, выглядит следующим образом:

remote_file 'name' do
  atomic_update              true, false
  authentication             # default value: remote
  backup                     Integer, false # default value: 5
  checksum                   String
  content                    String, nil
  force_unlink               true, false # default value: false
  ftp_active_mode            true, false # default value: false
  group                      String, Integer
  headers                    Hash
  inherits                   true, false
  manage_symlink_source      true, false
  mode                       String, Integer
  notifies                   # see description
  owner                      String, Integer
  path                       String # defaults to 'name' if not specified
  rights                     Hash
  source                     String, Array
  subscribes                 # see description
  use_conditional_get        true, false
  verify                     String, Block
  remote_domain              String
  remote_password            String
  remote_user                String
  show_progress              true, false # default value: false
  use_etag                   true, false # default value: true
  use_last_modified          true, false # default value: true
  sensitive                  true, false # default value: false
  verifications              Array
  action                     Symbol # defaults to :create if not specified
end

где:

• remote_file — это ресурс.
• name — имя, данное блоку ресурсов.
• action определяет, какие действия выполнит Chef Infra Client, чтобы привести узел в желаемое состояние.
• atomic_update, authentication, backup, checksum, content, force_unlink, ftp_active_mode, group, headers, http_options, manage_symlink_source, mode, owner, path, remote_domain, remote_password, remote_user, show_progress, ssl_verify_mode, use_etag и use_last_modified — это свойства, доступные для этого ресурса.

Действия

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

:create

По умолчанию. Создать файл. Если файл уже существует (но не соответствует), обновить этот файл, чтобы он соответствовал.

:create_if_missing

Создать файл только если он не существует. Если файл существует, ничего не происходит.

:delete

Удалить файл.

:nothing

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

:touch

Создать файл. Обновляет время последнего доступа (atime) и время последнего изменения (mtime) файла. (Это действие может использоваться с этим ресурсом, но обычно используется только с ресурсом file.)

Свойства

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

authentication

Тип Ruby: Symbol | Значение по умолчанию: :remote Допустимые значения: :local, :remote

backup

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

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

checksum

Тип Ruby: String

Необязательно, см. use_conditional_get. Контрольная сумма SHA-256 файла. Используется для предотвращения повторной загрузки файла. Если локальный файл соответствует контрольной сумме, Chef Infra Client не загружает его.

force_unlink

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

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

ftp_active_mode

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

Использует ли Chef Infra Client активный или пассивный FTP. Установите значение true, чтобы использовать активный FTP.

group

Тип Ruby: Integer, String

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

headers

Тип Ruby: Hash | Значение по умолчанию: {}

Хэш пользовательских заголовков. Например:

headers({ "Cookie" => "user=user_name; pass=p@ssw0rd!" })

или:

headers({ "Referer" => "#{header}" })

или:

headers( "Authorization"=>"Basic #{ Base64.encode64("#{username}:#{password}").gsub("\n", "") }" )

inherits

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

Только для Microsoft Windows. Наследует ли файл права от своего родительского каталога.

http_options

Тип Ruby: Hash | Значение по умолчанию: {}

Хэш пользовательских параметров HTTP. Например: http_options({ http_retry_count: 0, http_retry_delay: 2 })

Новое в Chef Infra Client 17.5

manage_symlink_source

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

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

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

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

mode

Тип Ruby: Integer, String

Строка из 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: Integer, String

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

path

Тип Ruby: String | Значение по умолчанию: The resource block's name

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

remote_domain

Тип Ruby: Строка

Только для Windows Домен пользователя, указанный свойством remote_user. По умолчанию ресурс будет аутентифицироваться по домену удаленной системы или как локальный пользователь, если удаленная система не присоединена к домену. Если удаленная система не входит в домен, необходимо аутентифицироваться как локальный пользователь на удаленной системе, установив домен на ., например: remote_domain ‘.’. Домен также может быть указан как часть свойства remote_user.

Новое в Chef Client 13.4

remote_password

Тип Ruby: Строка

Только для Windows Пароль пользователя, указанного свойством remote_user . Это свойство обязательно, если задано remote_user, и может быть задано только если задано remote_user . Свойство sensitive для данного ресурса будет автоматически установлено на true , если задано remote_password.

Новое в Chef Client 13.4

remote_user

Тип Ruby: Строка

Только для Windows Имя пользователя с доступом к удаленному файлу, указанному свойством source. Имя пользователя может быть необязательно указано с доменом, например: domain\user или user@my.dns.domain.com в формате Universal Principal Name (UPN). Домен также может быть задан с помощью свойства remote_domain . Обратите внимание, что это свойство игнорируется, если source не является UNC-путем. Если это свойство задано, свойство remote_password обязательно.

Новое в Chef Client 13.4

rights

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

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

source

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

Обязательно. Расположение исходного файла. Расположение исходного файла может быть HTTP (http://), FTP (ftp://), SFTP (sftp://), локальным (file:///) или UNC (\\host\share\file.tar.gz).

Существует множество способов определения расположения исходного файла. Используя путь:

source 'http://couchdb.apache.org/img/sketch.png'

Используя FTP:

source 'ftp://remote_host/path/to/img/sketch.png'

Используя SFTP:

source 'sftp://username:password@remote_host:22/path/to/img/sketch.png'

Используя локальный путь:

source 'file:///path/to/img/sketch.png'

Используя Microsoft Windows UNC:

source '\\\\path\\to\\img\\sketch.png'

Используя атрибут узла:

source node['nginx']['foo123']['url']

Используя атрибуты для определения путей:

source "#{node['python']['url']}/#{version}/Python-#{version}.tar.bz2"

Определяя несколько путей для нескольких расположений:

source 'http://seapower/spring.png', 'http://seapower/has_sprung.png'

Определяя те же самые несколько путей как массив:

source ['http://seapower/spring.png', 'http://seapower/has_sprung.png']

Когда указано несколько путей, Chef Infra Client попытается загрузить файлы в указанном порядке, остановившись после первой успешной загрузки.

use_conditional_get

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

Включить условные HTTP-запросы, используя условное GET (с заголовком If-Modified-Since) или непрозрачный идентификатор (ETag). Для использования заголовков If-Modified-Since, use_last_modified также должно быть установлено на true . Для использования заголовков ETag, use_etag также должно быть установлено на true.

show_progress

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

Отображает прогресс загрузки файла.

ssl_verify_mode

Тип Ruby: Символ Допустимые значения: :verify_none, :verify_peer

Необязательное свойство для переопределения политики SSL. Если не указано, используется политика SSL из config.rb.

Новое в Chef Infra Client 16.2

use_etag

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

Включить заголовки ETag. Установите на false для отключения заголовков ETag. Для использования этого параметра, use_conditional_get также должно быть установлено на true.

use_last_modified

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

Включить заголовки If-Modified-Since . Установите на false для отключения заголовков If-Modified-Since . Для использования этого параметра, use_conditional_get также должно быть установлено на true.

verify

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

Блок или строка, возвращающие true или false. Строка, когда true выполняется как системная команда.

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

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

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

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

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

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

remote_file '/tmp/bar' do
  verify { 1 == 1}
end

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

remote_file '/tmp/foo' do
  verify do |path|
    true
  end
end

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

remote_file '/tmp/turtle' do
  verify '/usr/bin/false'
end

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

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

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

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

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

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

rights permission, principal, option_type => value

где

permission

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

Целые числа, используемые для прав, должны соответствовать следующему списку FileSystemRights Enum поля.

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 Infra Client, которые уже присутствуют на узле, используйте один из следующих атрибутов в рецепте: use_conditional_get (по умолчанию) или checksum.

• Атрибут use_conditional_get — это поведение по умолчанию Chef Infra Client. Если удалённый файл находится на сервере, который поддерживает заголовки ETag и/или If-Modified-Since, Chef Infra Client будет использовать условную загрузку GET, чтобы определить, был ли файл обновлён. Если файл обновлён, Chef Infra Client перескачает файл.
• Атрибут checksum попросит Chef Infra Client сравнить контрольную сумму локального файла с контрольной суммой на удалённом сервере. Если они совпадают, Chef Infra Client не будет перескачивать файл. Использование локальной контрольной суммы для сравнения требует, чтобы локальная контрольная сумма была правильной.

Желаемый подход зависит от требуемой рабочей среды. Например, если узлу нужен новый файл каждый день, использование подхода контрольной суммы потребует обновления и/или проверки локальной контрольной суммы каждый день, чтобы убедиться, что локальная контрольная сумма правильная. Использование условной загрузки GET в этом случае значительно упростит управление, необходимое для точного обновления файлов.

Доступ к удалённому пути UNC на Windows

Ресурс remote_file на Windows поддерживает доступ к файлам с удалённого общего ресурса SMB/CIFS. Имя файла должно быть указано в свойстве source как путь UNC, например, \myserver\myshare\mydirectory\myfile.txt. Это позволяет получить доступ к файлу в этом расположении, даже если идентификатор процесса Chef Infra Client не имеет разрешения на доступ к файлу. Данные для аутентификации на удалённой системе можно указать с помощью свойств remote_user, remote_domain и remote_password, когда пользователь, под которым работает Chef Infra Client, не имеет доступа к удалённому файлу. Подробнее об этих вариантах см. раздел «Свойства».

Примечание: Это в первую очередь для доступа к удалённым файлам, когда пользователь, под которым работает Chef Infra Client, не имеет достаточного доступа, и необходимо указать альтернативные учетные данные. Если у пользователя уже есть доступ, указывать учетные данные не нужно. В случае, когда локальная и удалённая системы находятся в одном домене, свойства remote_user и remote_password часто не нужно указывать, так как у пользователя может быть доступ к удалённому общему ресурсу.

Примеры:

Доступ к файлу от учётной записи другого домена:

remote_file 'E:/domain_test.txt' do
  source '\\myserver\myshare\mydirectory\myfile.txt'
  remote_domain 'domain'
  remote_user 'username'
  remote_password 'password'
end

ИЛИ

remote_file 'E:/domain_test.txt' do
  source '\\myserver\myshare\mydirectory\myfile.txt'
  remote_user 'domain\username'
  remote_password 'password'
end

Доступ к файлу с использованием локальной учётной записи на удалённой машине:

remote_file 'E:/domain_test.txt' do
  source '\\myserver\myshare\mydirectory\myfile.txt'
  remote_domain '.'
  remote_user 'username'
  remote_password 'password'
end

ИЛИ

remote_file 'E:/domain_test.txt' do
  source '\\myserver\myshare\mydirectory\myfile.txt'
  remote_user '.\username'
  remote_password 'password'
end

Примеры

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

Загрузка файла без проверки контрольной суммы:

  remote_file '/tmp/remote.txt' do
    source 'https://example.org/remote.txt'
  end

Загрузка файла с контрольной суммой для проверки:

  remote_file '/tmp/test_file' do
    source 'http://www.example.com/tempfiles/test_file'
    mode '0755'
    checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
  end

Загрузка файла только в том случае, если он ещё не присутствует:

  remote_file '/tmp/remote.txt' do
    source 'https://example.org/remote.txt'
    checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
    action :create_if_missing
  end

Использование HTTP Basic аутентификации в заголовках:

  remote_file '/tmp/remote.txt' do
    source 'https://example.org/remote.txt'
    headers('Authorization' => "Basic #{Base64.encode64("USERNAME_VALUE:PASSWORD_VALUE").delete("\n")}")
    checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
    action :create_if_missing
  end

Загрузка файла в каталог кэша файлов Chef для выполнения:

  remote_file '#{Chef::Config['file_cache_path']}/install.sh' do
    source 'https://example.org/install.sh'
    action :create_if_missing
  end

  execute '#{Chef::Config['file_cache_path']}/install.sh'

Укажите расширенные параметры HTTP-соединения, включая параметры Net::HTTP (nethttp):

  remote_file '/tmp/remote.txt' do
    source 'https://example.org/remote.txt'
    http_options({
      http_retry_delay: 0,
      http_retry_count: 0,
      keepalives: false,
      nethttp: {
        continue_timeout: 5,
        max_retries: 5,
        read_timeout: 5,
        write_timeout: 5,
        ssl_timeout: 5,
      },
    })
  end