1Rex::Commands::Fs(3) User Contributed Perl Documentation Rex::Commands::Fs(3)
2
6 Rex::Commands::Fs - File system commands
7
9 With this module you can do file system tasks like creating
10 directories, deleting or moving files, and more.
11
13 my @files = list_files "/etc";
14 unlink("/tmp/file");
16 rmdir("/tmp");
18 mkdir("/tmp");
19 my %stat = stat("/etc/passwd");
21 my $link = readlink("/path/to/a/link");
23 symlink("/source", "/dest");
24 rename("oldname", "newname");
26 chdir("/tmp");
28 is_file("/etc/passwd");
30 is_dir("/etc");
31 is_writeable("/tmp");
32 is_writable("/tmp");
33 chmod 755, "/tmp";
35 chown "user", "/tmp";
36 chgrp "group", "/tmp";
37
39 Changing content
40 These commands are supposed to change the contents of the file system.
41 symlink($from, $to)
43 This function will create a symbolic link from $from to $to.
45 task "symlink", "server01", sub {
47 symlink("/var/www/versions/1.0.0", "/var/www/html");
48 };
49 ln($from, $to)
51 "ln" is an alias for "symlink"
53 unlink($file)
55 This function will remove the given $file.
57 task "unlink", "server01", sub {
59 unlink("/tmp/testfile");
60 };
61 rm($file)
63 This is an alias for "unlink".
65 rmdir($dir)
67 This function will remove the given directory.
69 task "rmdir", "server01", sub {
71 rmdir("/tmp");
72 };
73 With Rex-0.45 and newer, please use the file resource instead.
75 task "prepare", sub {
77 file "/tmp",
78 ensure => "absent";
79 };
80 mkdir($newdir)
82 This function will create a new directory.
84 The following options are supported:
86 • owner
88 • group
90 • mode
92 • on_change
94 With Rex-0.45 and newer, please use the file resource instead.
96 task "prepare", sub {
98 file "/tmp",
99 ensure => "directory",
100 owner => "root",
101 group => "root",
102 mode => 1777;
103 };
104 Direct usage:
106 task "mkdir", "server01", sub {
108 mkdir "/tmp";
109 mkdir "/tmp",
111 owner => "root",
112 group => "root",
113 mode => 1777;
114 };
115 chown($owner, $path)
117 Change the owner of a file or a directory.
119 chown "www-data", "/var/www/html";
121 chown "www-data", "/var/www/html",
123 recursive => 1;
124 This command will not be reported.
126 If you want to use reports, please use the file resource instead.
128 chgrp($group, $path)
130 Change the group of a file or a directory.
132 chgrp "nogroup", "/var/www/html";
134 chgrp "nogroup", "/var/www/html",
136 recursive => 1;
137 This command will not be reported.
139 If you want to use reports, please use the file resource instead.
141 chmod($mode, $path)
143 Change the permissions of a file or a directory.
145 chmod 755, "/var/www/html";
147 chmod 755, "/var/www/html",
149 recursive => 1;
150 This command will not be reported.
152 If you want to use reports, please use the file resource instead.
154 rename($old, $new)
156 This function will rename $old to $new. Will return 1 on success and 0
158 on failure.
159 task "rename", "server01", sub {
161 rename("/tmp/old", "/tmp/new");
162 };
163 mv($old, $new)
165 "mv" is an alias for "rename".
167 cp($source, $destination)
169 "cp" will copy $source to $destination recursively.
171 task "cp", "server01", sub {
173 cp("/var/www", "/var/www.old");
174 };
175 Not changing content
177 These commands should not change the contents of the file system.
178 list_files("/path");
180 This function lists all entries (files, directories, ...) in a given
182 directory and returns them as an array.
183 task "ls-etc", "server01", sub {
185 my @tmp_files = grep { /\.tmp$/ } list_files("/etc");
186 };
187 This command will not be reported.
189 ls($path)
191 Just an alias for "list_files".
193 stat($file)
195 This function will return a hash with the following information about a
197 file or directory:
198 mode
200 size
201 uid
202 gid
203 atime
204 mtime
205 task "stat", "server01", sub {
207 my %file_stat = stat("/etc/passwd");
208 };
209 This command will not be reported.
211 is_file($path)
213 This function tests if $path is a file. Returns 1 if true, 0 if false.
215 task "isfile", "server01", sub {
217 if( is_file("/etc/passwd") ) {
218 say "it is a file.";
219 }
220 else {
221 say "hm, this is not a file.";
222 }
223 };
224 This command will not be reported.
226 is_dir($path)
228 This function tests if $path is a directory. Returns 1 if true, 0 if
230 false.
231 task "isdir", "server01", sub {
233 if( is_dir("/etc") ) {
234 say "it is a directory.";
235 }
236 else {
237 say "hm, this is not a directory.";
238 }
239 };
240 This command will not be reported.
242 is_symlink($path)
244 This function tests if $path is a symbolic link. Returns 1 if true, 0
246 if false.
247 task "issym", "server01", sub {
249 if( is_symlink("/etc/foo.txt") ) {
250 say "it is a symlink.";
251 }
252 else {
253 say "hm, this is not a symlink.";
254 }
255 };
256 This command will not be reported.
258 is_readable($path)
260 This function tests if $path is readable. It returns 1 if true, 0 if
262 false.
263 task "readable", "server01", sub {
265 if( is_readable("/etc/passwd") ) {
266 say "passwd is readable";
267 }
268 else {
269 say "not readable.";
270 }
271 };
272 This command will not be reported.
274 is_writable($path)
276 This function tests if $path is writable. It returns 1 if true, 0 if
278 false.
279 task "writable", "server01", sub {
281 if( is_writable("/etc/passwd") ) {
282 say "passwd is writable";
283 }
284 else {
285 say "not writable.";
286 }
287 };
288 This command will not be reported.
290 is_writeable($file)
292 This is only an alias for "is_writable".
294 readlink($link)
296 If $link is a symbolic link, returns the path it resolves to, and
298 die()s otherwise.
299 task "islink", "server01", sub {
301 my $link;
302 eval {
303 $link = readlink("/tmp/testlink");
304 };
305 say "this is a link" if($link);
307 };
308 This command will not be reported.
310 chdir($newdir)
312 This function will change the working directory to $newdir. This
314 function currently works only locally.
315 task "chdir", "server01", sub {
317 chdir("/tmp");
318 };
319 This command will not be reported.
321 cd($newdir)
323 This is an alias of "chdir".
325 df([$device])
327 This function returns a hash reference which reflects the output of
329 "df".
330 task "df", "server01", sub {
332 my $df = df();
333 my $df_on_sda1 = df("/dev/sda1");
334 };
335 This command will not be reported.
337 du($path)
339 Returns the disk usage of $path.
341 task "du", "server01", sub {
343 say "size of /var/www: " . du("/var/www");
344 };
345 This command will not be reported.
347 mount($device, $mount_point, @options)
349 Mount devices.
351 task "mount", "server01", sub {
353 mount "/dev/sda5", "/tmp";
354 mount "/dev/sda6", "/mnt/sda6",
355 ensure => "present",
356 type => "ext3",
357 options => [qw/noatime async/],
358 on_change => sub { say "device mounted"; };
359 #
360 # mount persistent with entry in /etc/fstab
361 mount "/dev/sda6", "/mnt/sda6",
363 ensure => "persistent",
364 type => "ext3",
365 options => [qw/noatime async/],
366 on_change => sub { say "device mounted"; };
367 # to umount a device
369 mount "/dev/sda6", "/mnt/sda6",
370 ensure => "absent";
371 };
373 In order to be more aligned with "mount" terminology, the previously
375 used "fs" option has been deprecated in favor of the "type" option. The
376 "fs" option is still supported and works as previously, but Rex prints
377 a warning if it is being used. There's also a warning if both "fs" and
378 "type" options are specified, and in this case "type" will be used.
379 umount($mount_point)
381 Unmount device.
383 task "umount", "server01", sub {
385 umount "/tmp";
386 };
387 glob($glob)
389 Returns the list of filename expansions for $glob as Perl's built-in
391 glob <https://perldoc.perl.org/functions/glob.html> would do.
392 task "glob", "server1", sub {
394 my @files_with_p = grep { is_file($_) } glob("/etc/p*");
395 };
396 This command will not be reported.
398perl v5.38.0 2023-08-07 Rex::Commands::Fs(3)