link Resource
This page is generated from the Chef Infra Client source code.To suggest a change, edit the link.rb file and submit a pull request to the Chef Infra Client repository.
Use the link resource to create symbolic or hard links.
A symbolic link–sometimes referred to as a soft link–is a directory entry that associates a file name with a string that contains an absolute or relative path to a file on any file system. In other words, it’s a file that contains a path that points to another file. A symbolic link creates a new file with a new inode that points to the inode location of the original file.
A hard link is a directory entry that associates a file with another file in the same file system. In other words, multiple directory entries to the same file. A hard link creates a new file that points to the same inode as the original file.
Syntax
A link resource block creates symbolic or hard links. For
example, to create a hard link from /tmp/file
to /etc/file
:
link '/tmp/file' do
to '/etc/file'
link_type :hard
end
Because the default value for link_type
is symbolic, and because
properties that are not specified in the resource block will be assigned
their default values, the following example creates a symbolic link:
link '/tmp/file' do
to '/etc/file'
end
The full syntax for all of the properties that are available to the link resource is:
link 'name' do
group String, Integer
link_type String, Symbol # default value: :symbolic
owner String, Integer
target_file String # default value: 'name' unless specified
to String
action Symbol # defaults to :create if not specified
end
where:
link
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.group
,link_type
,owner
,target_file
, andto
are the properties available to this resource.
Actions
The link resource has the following actions:
:create
- (default) Create a link. If a link already exists (but does not match), update that link to match.
:delete
- Delete a link.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The link resource has the following properties:
group
- Ruby Type: String, Integer
A group name or ID number that identifies the group associated with a symbolic link.
link_type
- Ruby Type: String, Symbol | Default Value:
:symbolic
Allowed Values::hard, :symbolic
The type of link:
:symbolic
or:hard
. On Windows,:symbolic
will create a junction point if the target is a directory.
mode
- Ruby Type: Integer, String | Default Value:
777
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, Chef Infra 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'
, Chef Infra 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.
owner
- Ruby Type: String, Integer
The owner associated with a symbolic link.
target_file
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the target file if it differs from the resource block’s name.
to
- Ruby Type: String
The actual file to which the link is to be created.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
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.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra 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 a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
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 the nginx
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
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra 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 a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the link resource in recipes:
Create symbolic links
The following example will create a symbolic link from /tmp/file
to /etc/file
:
link '/tmp/file' do
to '/etc/file'
end
Create hard links
The following example will create a hard link from /tmp/file
to /etc/file
:
link '/tmp/file' do
to '/etc/file'
link_type :hard
end
Delete links
The following example will delete the /tmp/file
symbolic link and uses
the only_if
guard to run the test -L
command, which verifies that
/tmp/file
is a symbolic link, and then only deletes /tmp/file
if the
test passes:
link '/tmp/file' do
action :delete
only_if
'test -L /tmp/file'
end
Create multiple symbolic links
The following example creates symbolic links from two files in the /vol/webserver/cert/
directory to files located in the /etc/ssl/certs/
directory:
link '/vol/webserver/cert/server.crt' do
to '/etc/ssl/certs/ssl-cert-name.pem'
end
link '/vol/webserver/cert/server.key' do
to '/etc/ssl/certs/ssl-cert-name.key'
end
Create platform-specific symbolic links
The following example shows installing a filter module on Apache. The package name is different for different platforms, and for the Red Hat Enterprise Linux family, a symbolic link is required:
include_recipe 'apache2::default'
case node['platform_family']
when 'debian'
...
when 'suse'
...
when 'rhel', 'fedora'
...
link '/usr/lib64/httpd/modules/mod_apreq.so' do
to '/usr/lib64/httpd/modules/mod_apreq2.so'
only_if 'test -f /usr/lib64/httpd/modules/mod_apreq2.so'
end
link '/usr/lib/httpd/modules/mod_apreq.so' do
to '/usr/lib/httpd/modules/mod_apreq2.so'
only_if 'test -f /usr/lib/httpd/modules/mod_apreq2.so'
end
end
...
For the complete recipe, see https://github.com/onehealth-cookbooks/apache2/blob/68bdfba4680e70b3e90f77e40223dd535bf22c17/recipes/mod_apreq2.rb.
Create Windows junction/reparse points
This example demonstrates how to create a directory junction/reparse point. In this example, C:\\destination
will be a junction/reparse point to the C:\\source
directory.
directory 'C:/source'
link 'C:/destination' do
link_type :symbolic
to 'C:/source'
end