A resource defines the desired state for a single configuration item present on a node that is under management by Chef. A resource collection—one (or more) individual resources—defines the desired state for the entire node. During every chef-client run, the current state of each resource is tested, after which the chef-client will take any steps that are necessary to repair the node and bring it back into the desired state.
Use the file resource to manage files that are present on a node, including setting or updating the contents of those files.
Other resources should be used to manage files that are not present on a node. Use cookbook_file when copying a file from a cookbook, template when using a template, and remote_file when transferring files from remote locations.
The syntax for using the file resource in a recipe is as follows:
file "name" do attribute "value" # see attributes section below ... action :action # see actions section below end
The following is an example of how the file resource can work when used in a recipe:
file "/tmp/something" do owner "root" group "root" mode "0755" action :create end
This resource has the following actions:
|:create||Default. Use to create a file. If a file already exists (but does not match), use to update that file to match.|
|:create_if_missing||Use to create a file only if the file does not exist. (When the file exists, nothing happens.)|
|:delete||Use to delete a file.|
|:touch||Use to touch a file. This updates the access (atime) and file modification (mtime) times for a file.|
This resource has the following attributes:
|atomic_update||Use to perform atomic file updates on a per-resource basis. Set to true for atomic file updates. Set to false for non-atomic file updates. (This setting overrides file_atomic_update, which is a global setting found in the client.rb file.) Default value: true.|
|backup||The number of backups to be kept. Set to false to prevent backups from being kept. Default value: 5.|
|content||A string that is written to the file. The contents of this attribute will replace any previous content when this attribute has something other than the default value. The default behavior will not modify content.|
|force_unlink||Use to specify how the chef-client handles certain situations when the target file turns out not to be a file. For example, when a target file is actually a symlink. Set to true to have the chef-client delete the non-file target and replace it with the specified file. Set to false for the chef-client to raise an error. Default value: false.|
|group||A string or ID that identifies the group owner by group name, including fully qualified group names such as domain\group or group@domain. If this value is not specified, existing groups will remain unchanged and new group assignments will use the default POSIX group (if available).|
|inherits||Microsoft Windows only. Use to specify that a file inherits rights from its parent directory. Default value: true.|
|manage_symlink_source||Use to have the chef-client detect and manage the source file for a symlink. Possible values: nil, true, or false. When this value is set to nil, the chef-client will manage a symlink’s source file and emit a warning. When this value is set to true, the chef-client will manage a symlink’s source file and not emit a warning. Default value: nil. The default value will be changed to false in a future version.|
A quoted string that defines the octal mode for a file. If mode is not specified and if the file already exists, the existing mode on the file is used. If mode is not specified, the file does not exist, and the :create action is specified, the chef-client will assume a mask value of "0777" and then apply the umask for the system on which the file will be created to the mask value. For example, if the umask on a system is "022", the chef-client would use the default value of "0755".
The behavior is different depending on the platform.
UNIX- and Linux-based systems: A quoted string that defines the octal mode that is passed to chmod. If the value is specified as a quoted string, it will work exactly as if the chmod command was passed. If the value is specified as an integer, prepend a zero (0) to the value to ensure 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, use "01777" or "1777".
Microsoft Windows: A quoted string that defines the octal mode that is translated into rights for Microsoft Windows security. Values up to "0777" are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where 4 equals GENERIC_READ, 2 equals GENERIC_WRITE, and 1 equals GENERIC_EXECUTE. This attribute cannot be used to set :full_control. This attribute has no effect if not specified, but when this attribute and rights are both specified, the effects will be cumulative.
|owner||A string or ID that identifies the group owner by user name, including fully qualified user names such as domain\user or user@domain. If this value is not specified, existing owners will remain unchanged and new owner assignments will use the current user (when necessary).|
The path to the file. Using a fully qualified path is recommended, but is not always required. Default value: the name of the resource block (see Syntax section above).
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.
|provider||Optional. Use to specify a provider by using its long name. For example: provider Chef::Provider::Long::Name. See the Providers section below for the list of providers available to this resource.|
|rights||Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. For example: rights <permissions>, <principal>, <options> where <permissions> specifies the rights granted to the principal, <principal> is the group or user name, and <options> is a Hash with one (or more) advanced rights options.|
For a machine on which SELinux is enabled, the chef-client will create files that correctly match the default policy settings only when the cookbook that defines the action also conforms to the same policy.
Atomic updates are used with file-based resources to help ensure that file updates can be made when updating a binary or if disk space runs out.
Atomic updates are enabled by default. They can be managed globally using the file_atomic_update attribute in the client.rb file. They can be managed on a per-resource basis using the atomic_update attribute that is available with the cookbook_file, file, remote_file, and template resources.
On certain platforms, and after a file has been moved into place, the chef-client may modify file permissions to support features specific to those platforms. On platforms with SELinux enabled, the chef-client will fix up the security contexts after a file has been moved into the correct location by running the restorecon command. On the Microsoft Windows platform, the chef-client will create files so that ACL inheritance works as expected.
To support Microsoft Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes.
Access Control Lists (ACLs)
The rights attribute can be used in a recipe to manage access control lists (ACLs), which allow permissions to be given to multiple users and groups. The syntax for the rights attribute is as follows:
rights permission, principal, option_type => value
permission is used to specify which rights will be granted to the principal. The possible values are: :read, :write, read_execute, :modify, :full_control, and :deny.
These permissions are cumulative. If :write is specified, then it includes :read. If :full_control is specified, then it includes both :write and :read. If :deny is specified, then the user or group will not have rights to the object.
(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 is used to specify a group or user name. This is identical to what is entered in the login box for Microsoft Windows, such as user_name, domain\user_name, or user_name@fully_qualified_domain_name. The chef-client does not need to know if a principal is a user or a group.
option_type is a hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like: rights :write, "domain\group_name", :one_level_deep => true. Possible option types:
Option Type Description :applies_to_children Use to specify how permissions are applied to children. Possible values: true to inherit both child directories and files; false to not inherit any child directories or files; :containers_only to inherit only child directories (and not files); :objects_only to recursively inherit files (and not child directories). :applies_to_self Indicates whether a permission is applied to the parent directory. Possible values: true to apply to the parent directory or file and its children; false to not apply only to child directories and files. :one_level_deep Indicates the depth to which permissions will be applied. Possible values: true to apply only to the first level of children; false to apply to all children.
The rights attribute can be used as many times as necessary; the chef-client will apply them to the file or directory as required. For example:
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 end
rights :read, ["Administrators","Everyone"] rights :deny, ["Julian", "Lewis"] rights :full_control, "Users", :applies_to_children => true rights :write, "Sally", :applies_to_children => :containers_only, :applies_to_self => false, :one_level_deep => true
Some other important things to know when using the rights attribute:
By default, a file or directory inherits rights from its parent directory. Most of the time this is the preferred behavior, but sometimes it may be necessary to take steps to more specifically control rights. The inherits attribute can be used to specifically tell the chef-client to apply (or not apply) inherited rights from its parent directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do rights :read, 'MORDOR\Minions' rights :full_control, 'MORDOR\Sauron' end
and then the following example specifies how to use inheritance to deny access to the child directory:
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
If the :deny permission were to be used instead, something could slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
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
but then not use the inherits attribute to deny those rights on a child directory:
directory 'C:\mordor\mount_doom' do rights :deny, 'MORDOR\Minions' # Oops, not specific enough end
Because the inherits attribute is not specified, the chef-client will default it to true, which will ensure that security settings for existing files remain unchanged.
The following providers are available. Use the short name to call the provider from a recipe:
|Long name||Short name||Notes|
|Chef::Provider::File||file||The default provider for all platforms.|
The following examples demonstrate various approaches for using resources in recipes. If you want to see examples of how Chef uses resources in recipes, take a closer look at the cookbooks that Chef authors and maintains: https://github.com/opscode-cookbooks.
Create a file
file "/tmp/something" do owner "root" group "root" mode "0755" action :create end
Create a file in Microsoft Windows
file "C:\tmp\something.txt" do rights :read, "Everyone" rights :full_control, "DOMAIN\User" action :create end
Remove a file
file "/tmp/something" do action :delete end
Set file modes
file "/tmp/something" do mode "0644" end
Delete a repository using yum to scrub the cache
# 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