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 "File was changed."; };
48
50 template($file, @params)
51 Parse a template and return the content.
52 my $content = template("/files/templates/vhosts.tpl",
54 name => "test.lan",
55 webmaster => 'webmaster@test.lan');
56 The file name specified is subject to "path_map" processing as
58 documented under the file() function to resolve to a physical file
59 name.
60 In addition to the "path_map" processing, if the -E command line switch
62 is used to specify an environment name, existence of a file ending with
63 '.<env>' is checked and has precedence over the file without one, if it
64 exists. E.g. if rex is started as:
65 $ rex -E prod task1
67 then in task1 defined as:
69 task "task1", sub {
71 say template("files/etc/ntpd.conf");
73 };
75 will print the content of 'files/etc/ntpd.conf.prod' if it exists.
77 Note: the appended environment mechanism is always applied, after the
79 'path_map' mechanism, if that is configured.
80 file($file_name, %options)
82 This function is the successor of install file. Please use this
83 function to upload files to your server.
84 task "prepare", "server1", "server2", sub {
86 file "/file/on/remote/machine",
87 source => "/file/on/local/machine";
88 file "/etc/hosts",
90 content => template("templates/etc/hosts.tpl"),
91 owner => "user",
92 group => "group",
93 mode => 700,
94 on_change => sub { say "Something was changed." };
95 file "/etc/motd",
97 content => `fortune`;
98 file "/etc/named.conf",
100 content => template("templates/etc/named.conf.tpl"),
101 no_overwrite => TRUE; # this file will not be overwritten if already exists.
102 file "/etc/httpd/conf/httpd.conf",
104 source => "/files/etc/httpd/conf/httpd.conf",
105 on_change => sub { service httpd => "restart"; };
106 file "/etc/named.d",
108 ensure => "directory", # this will create a directory
109 owner => "root",
110 group => "root";
111 file "/etc/motd",
113 ensure => "absent"; # this will remove the file or directory
114 };
116 The first parameter is either a string or an array reference. In the
118 latter case the function is called for all strings in the array.
119 Therefore, the following constructs are equivalent:
120 file '/tmp/test1', ensure => 'directory';
122 file '/tmp/test2', ensure => 'directory';
123 file [ qw( /tmp/test1 /tmp/test2 ) ], ensure => 'directory'; # use array ref
125 file [ glob('/tmp/test{1,2}') ], ensure => 'directory'; # explicit glob call for array contents
127 Use the glob carefully as it can leak local filesystem information
129 (e.g. when using wildcards).
130 The source is subject to a path resolution algorithm. This algorithm
132 can be configured using the set function to set the value of the
133 path_map variable to a hash containing path prefixes as its keys. The
134 associated values are arrays listing the prefix replacements in order
135 of (decreasing) priority.
136 set "path_map", {
138 "files/" => [ "files/{environment}/{hostname}/_root_/",
139 "files/{environment}/_root_/" ]
140 };
141 With this configuration, the file "files/etc/ntpd.conf" will be probed
143 for in the following locations:
144 - files/{environment}/{hostname}/_root_/etc/ntpd.conf
146 - files/{environment}/_root_/etc/ntpd.conf
147 - files/etc/ntpd.conf
148 Furthermore, if a path prefix matches multiple prefix entries in
150 'path_map', e.g. "files/etc/ntpd.conf" matching both "files/" and
151 "files/etc/", the longer matching prefix(es) have precedence over
152 shorter ones. Note that keys without a trailing slash (i.e.
153 "files/etc") will be treated as having a trailing slash when matching
154 the prefix ("files/etc/").
155 If no file is found using the above procedure and source is relative,
157 it will search from the location of your Rexfile or the .pm file if you
158 use Perl packages.
159 All the possible variables ('{environment}', '{hostname}', ...) are
161 documented in the CMDB YAML documentation.
162 This function supports the following hooks:
164 before This gets executed before everything is done. The return value
166 of this hook overwrite the original parameters of the function-
167 call.
168 before_change
170 This gets executed right before the new file is written. Only
171 with content parameter. For the source parameter the hook of
172 the upload function is used.
173 after_change
175 This gets executed right after the file was written. Only with
176 content parameter. For the source parameter the hook of the
177 upload function is used.
178 after This gets executed right before the file() function returns.
180 file_write($file_name)
182 This function opens a file for writing (it will truncate the file if it
183 already exists). It returns a Rex::FS::File object on success.
184 On failure it will die.
186 my $fh;
188 eval {
189 $fh = file_write("/etc/groups");
190 };
191 # catch an error
193 if($@) {
194 print "An error occured. $@.\n";
195 }
196 # work with the filehandle
198 $fh->write("...");
199 $fh->close;
200 file_append($file_name)
202 file_read($file_name)
203 This function opens a file for reading. It returns a Rex::FS::File
204 object on success.
205 On failure it will die.
207 my $fh;
209 eval {
210 $fh = read("/etc/groups");
211 };
212 # catch an error
214 if($@) {
215 print "An error occured. $@.\n";
216 }
217 # work with the filehandle
219 my $content = $fh->read_all;
220 $fh->close;
221 cat($file_name)
223 This function returns the complete content of $file_name as a string.
224 print cat "/etc/passwd";
226 delete_lines_matching($file, $regexp)
228 Delete lines that match $regexp in $file.
229 task "clean-logs", sub {
231 delete_lines_matching "/var/log/auth.log" => "root";
232 };
233 delete_lines_according_to($search, $file, @options)
235 This is the successor of the delete_lines_matching() function. This
236 function also allows the usage of an on_change hook.
237 It will search for $search in $file and remove the found lines. If
239 on_change hook is present it will execute this if the file was changed.
240 task "cleanup", "server1", sub {
242 delete_lines_according_to qr{^foo:}, "/etc/passwd",
243 on_change => sub {
244 say "removed user foo.";
245 };
246 };
247 append_if_no_such_line($file, $new_line, @regexp)
249 Append $new_line to $file if none in @regexp is found. If no regexp is
250 supplied, the line is appended unless there is already an identical
251 line in $file.
252 task "add-group", sub {
254 append_if_no_such_line "/etc/groups", "mygroup:*:100:myuser1,myuser2", on_change => sub { service sshd => "restart"; };
255 };
256 Since 0.42 you can use named parameters as well
258 task "add-group", sub {
260 append_if_no_such_line "/etc/groups",
261 line => "mygroup:*:100:myuser1,myuser2",
262 regexp => qr{^mygroup},
263 on_change => sub {
264 say "file was changed, do something.";
265 };
266 append_if_no_such_line "/etc/groups",
268 line => "mygroup:*:100:myuser1,myuser2",
269 regexp => [qr{^mygroup:}, qr{^ourgroup:}]; # this is an OR
270 };
271 append_or_amend_line($file, $line, @regexp)
273 Similar to append_if_no_such_line, but if the line in the regexp is
274 found, it will be updated. Otherwise, it will be appended.
275 task "update-group", sub {
277 append_or_amend_line "/etc/groups",
278 line => "mygroup:*:100:myuser3,myuser4",
279 regexp => qr{^mygroup},
280 on_change => sub {
281 say "file was changed, do something.";
282 };
283 };
284 extract($file [, %options])
286 This function extracts a file. The target directory optionally
287 specified with the `to` option will be created automatically.
288 Supported formats are .box, .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2,
290 .tbz2, .zip, .gz, .bz2, .war, .jar.
291 task prepare => sub {
293 extract "/tmp/myfile.tar.gz",
294 owner => "root",
295 group => "root",
296 to => "/etc";
297 extract "/tmp/foo.tgz",
299 type => "tgz",
300 mode => "g+rwX";
301 };
302 Can use the type=> option if the file suffix has been changed. (types
304 are tar, tgz, tbz, zip, gz, bz2)
305 sed($search, $replace, $file)
307 Search some string in a file and replace it.
308 task sar => sub {
310 # this will work line by line
311 sed qr{search}, "replace", "/var/log/auth.log";
312 # to use it in a multiline way
314 sed qr{search}, "replace", "/var/log/auth.log",
315 multiline => TRUE;
316 };
317perl v5.30.0 2019-07-24 Rex::Commands::File(3)