1Rex::Commands::File(3)User Contributed Perl DocumentationRex::Commands::File(3)
2
6 Rex::Commands::File - Transparent File Manipulation
7
9 With this module you can manipulate files.
10
12 task "read_passwd", "server01", sub {
13 my $fh = file_read "/etc/passwd";
14 for my $line ($fh->read_all) {
15 print $line;
16 }
17 $fh->close;
18 };
19 task "read_passwd2", "server01", sub {
21 say cat "/etc/passwd";
22 };
23 task "write_passwd", "server01", sub {
26 my $fh = file_write "/etc/passwd";
27 $fh->write("root:*:0:0:root user:/root:/bin/sh\n");
28 $fh->close;
29 };
30 delete_lines_matching "/var/log/auth.log", matching => "root";
32 delete_lines_matching "/var/log/auth.log", matching => qr{Failed};
33 delete_lines_matching "/var/log/auth.log",
34 matching => "root", qr{Failed}, "nobody";
35 file "/path/on/the/remote/machine",
37 source => "/path/on/local/machine";
38 file "/path/on/the/remote/machine",
40 content => "foo bar";
41 file "/path/on/the/remote/machine",
43 source => "/path/on/local/machine",
44 owner => "root",
45 group => "root",
46 mode => 400,
47 on_change => sub { say shift, " was changed."; },
48 on_no_change => sub { say shift, " wasn't changed."; };
49
51 template($file, @params)
52 Parse a template and return the content.
53 By default, it uses Rex::Template. If any of the template_ng or 1.3 (or
55 newer) feature flag is enabled, then Rex::Template::NG is used instead
56 of this module (recommended).
57 For more advanced functionality, you may use your favorite template
59 engine via the set_template_function configuration option.
60 Embedded templates
62 Use "__DATA__" to embed templates at the end of the file. Prefix
64 embedded template names with "@". If embedding multiple templates, mark
65 their end with @end.
66 Single template
68 my $content = template( '@hello', name => 'world' ); # Hello, world!
70 __DATA__
71 @hello
72 Hello, <%= $name -%>!
73 Multiple templates
75 Use @end to separate multiple templates inside "__DATA__".
77 my $content = template( '@hello', name => 'world' ); # Hello, world!
79 my $alternative = template( '@hi', name => 'world' ); # Hi, world!
80 __DATA__
82 @hello
83 Hello, <%= $name -%>!
84 @end
85 @hi
87 Hi, <%= $name -%>!
88 @end
89 File templates
91 my $content = template("/files/templates/vhosts.tpl",
93 name => "test.lan",
94 webmaster => 'webmaster@test.lan');
95 The file name specified is subject to "path_map" processing as
97 documented under the file() function to resolve to a physical file
98 name.
99 In addition to the "path_map" processing, if the -E command line switch
101 is used to specify an environment name, existence of a file ending with
102 '.<env>' is checked and has precedence over the file without one, if it
103 exists. E.g. if rex is started as:
104 $ rex -E prod task1
106 then in task1 defined as:
108 task "task1", sub {
110 say template("files/etc/ntpd.conf");
111 };
112 will print the content of 'files/etc/ntpd.conf.prod' if it exists.
114 Note: the appended environment mechanism is always applied, after the
116 'path_map' mechanism, if that is configured.
117 file($file_name, %options)
119 This function is the successor of install file. Please use this
120 function to upload files to your server.
121 task "prepare", "server1", "server2", sub {
123 file "/file/on/remote/machine",
124 source => "/file/on/local/machine";
125 file "/etc/hosts",
127 content => template("templates/etc/hosts.tpl"),
128 owner => "user",
129 group => "group",
130 mode => 700,
131 on_change => sub { say "Something was changed." },
132 on_no_change => sub { say "Nothing has changed." };
133 file "/etc/motd",
135 content => `fortune`;
136 file "/etc/named.conf",
138 content => template("templates/etc/named.conf.tpl"),
139 no_overwrite => TRUE; # this file will not be overwritten if already exists.
140 file "/etc/httpd/conf/httpd.conf",
142 source => "/files/etc/httpd/conf/httpd.conf",
143 on_change => sub { service httpd => "restart"; };
144 file "/etc/named.d",
146 ensure => "directory", # this will create a directory
147 owner => "root",
148 group => "root";
149 file "/etc/motd",
151 ensure => "absent"; # this will remove the file or directory
152 };
154 The first parameter is either a string or an array reference. In the
156 latter case the function is called for all strings in the array.
157 Therefore, the following constructs are equivalent:
158 file '/tmp/test1', ensure => 'directory';
160 file '/tmp/test2', ensure => 'directory';
161 file [ qw( /tmp/test1 /tmp/test2 ) ], ensure => 'directory'; # use array ref
163 file [ glob('/tmp/test{1,2}') ], ensure => 'directory'; # explicit glob call for array contents
165 Use the glob carefully as it can leak local filesystem information
167 (e.g. when using wildcards).
168 The source is subject to a path resolution algorithm. This algorithm
170 can be configured using the set function to set the value of the
171 path_map variable to a hash containing path prefixes as its keys. The
172 associated values are arrays listing the prefix replacements in order
173 of (decreasing) priority.
174 set "path_map", {
176 "files/" => [ "files/{environment}/{hostname}/_root_/",
177 "files/{environment}/_root_/" ]
178 };
179 With this configuration, the file "files/etc/ntpd.conf" will be probed
181 for in the following locations:
182 - files/{environment}/{hostname}/_root_/etc/ntpd.conf
184 - files/{environment}/_root_/etc/ntpd.conf
185 - files/etc/ntpd.conf
186 Furthermore, if a path prefix matches multiple prefix entries in
188 'path_map', e.g. "files/etc/ntpd.conf" matching both "files/" and
189 "files/etc/", the longer matching prefix(es) have precedence over
190 shorter ones. Note that keys without a trailing slash (i.e.
191 "files/etc") will be treated as having a trailing slash when matching
192 the prefix ("files/etc/").
193 If no file is found using the above procedure and source is relative,
195 it will search from the location of your Rexfile or the .pm file if you
196 use Perl packages.
197 All the possible variables ('{environment}', '{hostname}', ...) are
199 documented in the CMDB YAML documentation.
200 Hooks
202 This function supports the following hooks:
204 before
206 This gets executed before anything is done. All original parameters
207 are passed to it, including the applied defaults ("ensure =>
208 'present'", resolved path for "source").
209 The return value of this hook overwrites the original parameters of
211 the function call.
212 before_change
214 This gets executed right before the new file is written. All
215 original parameters are passed to it, including the applied
216 defaults ("ensure => 'present'", resolved path for "source").
217 after_change
219 This gets executed right after the file is written. All original
220 parameters, including the applied defaults ("ensure => 'present'",
221 resolved path for "source"), and any returned results are passed to
222 it.
223 after
225 This gets executed right before the "file()" function returns. All
226 original parameters, including the applied defaults ("ensure =>
227 'present'", resolved path for "source"), and any returned results
228 are passed to it.
229 file_write($file_name)
231 This function opens a file for writing (it will truncate the file if it
232 already exists). It returns a Rex::FS::File object on success.
233 On failure it will die.
235 my $fh;
237 eval {
238 $fh = file_write("/etc/groups");
239 };
240 # catch an error
242 if($@) {
243 print "An error occurred. $@.\n";
244 }
245 # work with the filehandle
247 $fh->write("...");
248 $fh->close;
249 file_append($file_name)
251 file_read($file_name)
252 This function opens a file for reading. It returns a Rex::FS::File
253 object on success.
254 On failure it will die.
256 my $fh;
258 eval {
259 $fh = read("/etc/groups");
260 };
261 # catch an error
263 if($@) {
264 print "An error occurred. $@.\n";
265 }
266 # work with the filehandle
268 my $content = $fh->read_all;
269 $fh->close;
270 cat($file_name)
272 This function returns the complete content of $file_name as a string.
273 print cat "/etc/passwd";
275 delete_lines_matching($file, $regexp)
277 Delete lines that match $regexp in $file.
278 task "clean-logs", sub {
280 delete_lines_matching "/var/log/auth.log" => "root";
281 };
282 delete_lines_according_to($search, $file, @options)
284 This is the successor of the delete_lines_matching() function. This
285 function also allows the usage of on_change and on_no_change hooks.
286 It will search for $search in $file and remove the found lines. If
288 on_change hook is present it will execute this if the file was changed.
289 task "cleanup", "server1", sub {
291 delete_lines_according_to qr{^foo:}, "/etc/passwd",
292 on_change => sub {
293 say "removed user foo.";
294 };
295 };
296 append_if_no_such_line($file, $new_line, @regexp)
298 Append $new_line to $file if none in @regexp is found. If no regexp is
299 supplied, the line is appended unless there is already an identical
300 line in $file.
301 task "add-group", sub {
303 append_if_no_such_line "/etc/groups", "mygroup:*:100:myuser1,myuser2", on_change => sub { service sshd => "restart"; };
304 };
305 Since 0.42 you can use named parameters as well
307 task "add-group", sub {
309 append_if_no_such_line "/etc/groups",
310 line => "mygroup:*:100:myuser1,myuser2",
311 regexp => qr{^mygroup},
312 on_change => sub {
313 say "file was changed, do something.";
314 };
315 append_if_no_such_line "/etc/groups",
317 line => "mygroup:*:100:myuser1,myuser2",
318 regexp => [qr{^mygroup:}, qr{^ourgroup:}]; # this is an OR
319 };
320 append_or_amend_line($file, $line, @regexp)
322 Similar to append_if_no_such_line, but if the line in the regexp is
323 found, it will be updated. Otherwise, it will be appended.
324 task "update-group", sub {
326 append_or_amend_line "/etc/groups",
327 line => "mygroup:*:100:myuser3,myuser4",
328 regexp => qr{^mygroup},
329 on_change => sub {
330 say "file was changed, do something.";
331 },
332 on_no_change => sub {
333 say "file was not changed, do something.";
334 };
335 };
336 extract($file [, %options])
338 This function extracts a file. The target directory optionally
339 specified with the `to` option will be created automatically.
340 Supported formats are .box, .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2,
342 .tbz2, .zip, .gz, .bz2, .war, .jar.
343 task prepare => sub {
345 extract "/tmp/myfile.tar.gz",
346 owner => "root",
347 group => "root",
348 to => "/etc";
349 extract "/tmp/foo.tgz",
351 type => "tgz",
352 mode => "g+rwX";
353 };
354 Can use the type=> option if the file suffix has been changed. (types
356 are tar, tgz, tbz, zip, gz, bz2)
357 sed($search, $replace, $file)
359 Search some string in a file and replace it.
360 task sar => sub {
362 # this will work line by line
363 sed qr{search}, "replace", "/var/log/auth.log";
364 # to use it in a multiline way
366 sed qr{search}, "replace", "/var/log/auth.log",
367 multiline => TRUE;
368 };
369 Like similar file management commands, it also supports "on_change" and
371 "on_no_change" hooks.
372perl v5.36.0 2022-07-20 Rex::Commands::File(3)