machine_file¶
Use the machine_file resource to manage a file on a remote machine in much the same way the file resource is used to manage a file on a local machine.
Warning
This functionality is available with Chef provisioning and is packaged in the Chef development kit. Chef provisioning is a framework that allows clusters to be managed by the chef-client and the Chef server in the same way nodes are managed: with recipes. Use Chef provisioning to describe, version, deploy, and manage clusters of any size and complexity using a common set of tools.
Syntax¶
The syntax for using the machine_file resource in a recipe is as follows:
machine_file 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where
machine_file
tells the chef-client to use theChef::Provider::MachineFile
provider during the chef-client runname
is the name of the resource block; when thepath
property is not specified as part of a recipe,name
is also the path to a fileattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps the chef-client will take to bring the node into the desired state
Actions¶
This resource has the following actions:
:delete
- Use to delete a file from a machine.
:download
- Use to download a file from a machine.
:nothing
- Define this resource block to do nothing until notified by another resource to take action. When this resource is notified, this resource block is either run immediately or it is queued up to be run at the end of the Chef Client run.
:upload
- Default. Use to upload a file to a machine.
Properties¶
This resource has the following properties:
chef_server
Ruby Type: Hash
The URL for the Chef server.
content
- A string that is written to the file. The contents of this property replace any previous content when this property has something other than the default value. The default behavior will not modify content.
driver
Ruby Type: Chef::Provisioning::Driver
Use to specify the driver to be used for provisioning.
group
Ruby Type: String
A string or ID that identifies the group owner by group name, including fully qualified group names such as
domain\group
orgroup@domain
. If this value is not specified, existing groups remain unchanged and new group assignments use the defaultPOSIX
group (if available).ignore_failure
Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
local_path
Ruby Type: String
The local path to a file.
machine
Ruby Type: String
Use to specify the machine type.
mode
Ruby Type: String
If
mode
is not specified and if the file already exists, the existing mode on the file is used. Ifmode
is not specified, the file does not exist, and the:create
action is specified, the chef-client assumes a mask value of'0777'
and then applies the umask for the system on which the file is to be created to themask
value. For example, if the umask on a system is'022'
, the chef-client uses the default value of'0755'
.The behavior is different depending on the platform.
UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:
'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.notifies
Ruby Type: Symbol, ‘Chef::Resource[String]’
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.A timer specifies the point during the Chef Client run at which a notification is run. The following timers are available:
:before
- Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
- Default. Specifies that a notification should be queued up, and then executed at the end of the Chef Client run.
:immediate
,:immediately
- Specifies that a notification should be run immediately, per resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
owner
Ruby Type: String
A string or ID that identifies the group owner by user name, including fully qualified user names such as
domain\user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).path
Ruby Type: String
The full path to the file, including the file name and its extension. Default value: the
name
of the resource block. See “Syntax” section above for more information.Microsoft Windows: A path that begins with a forward slash (
/
) will point to the root of the current working directory of the chef-client process. This path can vary from system to system. Therefore, using a path that begins with a forward slash (/
) is not recommended.retries
Ruby Type: Integer | Default Value:
0
The number of times to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The retry delay (in seconds).
subscribes
Ruby Type: Symbol, ‘Chef::Resource[String]’
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example: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
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.A timer specifies the point during the Chef Client run at which a notification is run. The following timers are available:
:before
- Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
- Default. Specifies that a notification should be queued up, and then executed at the end of the Chef Client run.
:immediate
,:immediately
- Specifies that a notification should be run immediately, per resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples¶
Get a remote file onto a new machine
A deployment process requires more than just setting up machines. For example, files may need to be copied to machines from remote locations. The following example shows how to use the remote_file resource to grab a tarball from a URL, create a machine, copy that tarball to the machine, and then get that machine running by using a recipe that installs and configures that tarball on the machine:
remote_file 'mytarball.tgz' do
url 'https://myserver.com/mytarball.tgz'
end
machine 'x'
action :allocate
end
machine_file '/tmp/mytarball.tgz' do
machine 'x'
local_path 'mytarball.tgz'
action :upload
end
machine 'x' do
recipe 'untarthatthing'
action :converge
end