1Rex::Commands::Fs(3)  User Contributed Perl Documentation Rex::Commands::Fs(3)
2
3
4

NAME

6       Rex::Commands::Fs - Filesystem commands
7

DESCRIPTION

9       With this module you can do file system tasks like creating a
10       directory, deleting files, moving files, and more.
11

SYNOPSIS

13        my @files = list_files "/etc";
14
15        unlink("/tmp/file");
16
17        rmdir("/tmp");
18        mkdir("/tmp");
19
20        my %stat = stat("/etc/passwd");
21
22        my $link = readlink("/path/to/a/link");
23        symlink("/source", "/dest");
24
25        rename("oldname", "newname");
26
27        chdir("/tmp");
28
29        is_file("/etc/passwd");
30        is_dir("/etc");
31        is_writeable("/tmp");
32        is_writable("/tmp");
33
34        chmod 755, "/tmp";
35        chown "user", "/tmp";
36        chgrp "group", "/tmp";
37

EXPORTED FUNCTIONS

39   list_files("/path");
40       This function list all entries (files, directories, ...) in a given
41       directory and returns a array.
42
43        task "ls-etc", "server01", sub {
44          my @tmp_files = grep { /\.tmp$/ } list_files("/etc");
45        };
46
47       This command will not be reported.
48
49   ls($path)
50       Just an alias for list_files
51
52   symlink($from, $to)
53       This function will create a symlink from $from to $to.
54
55        task "symlink", "server01", sub {
56          symlink("/var/www/versions/1.0.0", "/var/www/html");
57        };
58
59   ln($from, $to)
60       ln is an alias for symlink
61
62   unlink($file)
63       This function will remove the given file.
64
65        task "unlink", "server01", sub {
66          unlink("/tmp/testfile");
67        };
68
69   rm($file)
70       This is an alias for unlink.
71
72   rmdir($dir)
73       This function will remove the given directory.
74
75        task "rmdir", "server01", sub {
76          rmdir("/tmp");
77        };
78
79       Since: 0.45 Please use the file() resource instead.
80
81        task "prepare", sub {
82          file "/tmp",
83            ensure => "absent";
84        };
85
86   mkdir($newdir)
87       This function will create a new directory.
88
89       Since: 0.45 Please use the file() resource instead.
90
91        task "prepare", sub {
92          file "/tmp",
93            ensure => "directory",
94            owner  => "root",
95            group  => "root",
96            mode   => 1777;
97        };
98
99        task "mkdir", "server01", sub {
100          mkdir "/tmp";
101
102          mkdir "/tmp",
103            owner => "root",
104            group => "root",
105            mode => 1777;
106        };
107
108   chown($owner, $file)
109       Change the owner of a file or a directory.
110
111        chown "www-data", "/var/www/html";
112
113        chown "www-data", "/var/www/html",
114                       recursive => 1;
115
116       This command will not be reported.
117
118       If you want to use reports, please use the file() resource instead.
119
120   chgrp($group, $file)
121       Change the group of a file or a directory.
122
123        chgrp "nogroup", "/var/www/html";
124
125        chgrp "nogroup", "/var/www/html",
126                     recursive => 1;
127
128       This command will not be reported.
129
130       If you want to use reports, please use the file() resource instead.
131
132   chmod($mode, $file)
133       Change the permissions of a file or a directory.
134
135        chmod 755, "/var/www/html";
136
137        chmod 755, "/var/www/html",
138                 recursive => 1;
139
140       This command will not be reported.
141
142       If you want to use reports, please use the file() resource instead.
143
144   stat($file)
145       This function will return a hash with the following information about a
146       file or directory.
147
148       mode
149       size
150       uid
151       gid
152       atime
153       mtime
154
155        task "stat", "server01", sub {
156          my %file_stat = stat("/etc/passwd");
157        };
158
159       This command will not be reported.
160
161   is_file($file)
162       This function tests if $file is a file. Returns 1 if true. 0 if false.
163
164        task "isfile", "server01", sub {
165          if( is_file("/etc/passwd") ) {
166            say "it is a file.";
167          }
168          else {
169            say "hm, this is not a file.";
170          }
171        };
172
173       This command will not be reported.
174
175   is_dir($dir)
176       This function tests if $dir is a directory. Returns 1 if true. 0 if
177       false.
178
179        task "isdir", "server01", sub {
180          if( is_dir("/etc") ) {
181            say "it is a directory.";
182          }
183          else {
184            say "hm, this is not a directory.";
185          }
186        };
187
188       This command will not be reported.
189
190   is_symlink($file)
191       This function tests if $file is a symlink. Returns 1 if true. 0 if
192       false.
193
194        task "issym", "server01", sub {
195          if( is_symlink("/etc/foo.txt") ) {
196            say "it is a symlink.";
197          }
198          else {
199            say "hm, this is not a symlink.";
200          }
201        };
202
203       This command will not be reported.
204
205   is_readable($file)
206       This function tests if $file is readable. It returns 1 if true. 0 if
207       false.
208
209        task "readable", "server01", sub {
210          if( is_readable("/etc/passwd") ) {
211            say "passwd is readable";
212          }
213          else {
214            say "not readable.";
215          }
216        };
217
218       This command will not be reported.
219
220   is_writable($file)
221       This function tests if $file is writable. It returns 1 if true. 0 if
222       false.
223
224        task "writable", "server01", sub {
225          if( is_writable("/etc/passwd") ) {
226            say "passwd is writable";
227          }
228          else {
229            say "not writable.";
230          }
231        };
232
233       This command will not be reported.
234
235   is_writeable($file)
236       This is only an alias for is_writable.
237
238       This command will not be reported.
239
240   readlink($link)
241       This function returns the link endpoint if $link is a symlink. If $link
242       is not a symlink it will die.
243
244        task "islink", "server01", sub {
245          my $link;
246          eval {
247            $link = readlink("/tmp/testlink");
248          };
249
250          say "this is a link" if($link);
251        };
252
253       This command will not be reported.
254
255   rename($old, $new)
256       This function will rename $old to $new. Will return 1 on success and 0
257       on failure.
258
259        task "rename", "server01", sub {
260          rename("/tmp/old", "/tmp/new");
261        };
262
263   mv($old, $new)
264       mv is an alias for rename.
265
266   chdir($newdir)
267       This function will change the current workdirectory to $newdir. This
268       function currently only works local.
269
270        task "chdir", "server01", sub {
271          chdir("/tmp");
272        };
273
274       This command will not be reported.
275
276   cd($newdir)
277       This is an alias of chdir.
278
279   df([$device])
280       This function returns a hashRef reflecting the output of df
281
282        task "df", "server01", sub {
283           my $df = df();
284           my $df_on_sda1 = df("/dev/sda1");
285        };
286
287       This command will not be reported.
288
289   du($path)
290       Returns the disk usage of $path.
291
292        task "du", "server01", sub {
293          say "size of /var/www: " . du("/var/www");
294        };
295
296       This command will not be reported.
297
298   cp($source, $destination)
299       cp will copy $source to $destination (it is recursive)
300
301        task "cp", "server01", sub {
302           cp("/var/www", "/var/www.old");
303        };
304
305   mount($device, $mount_point, @options)
306       Mount devices.
307
308        task "mount", "server01", sub {
309          mount "/dev/sda5", "/tmp";
310          mount "/dev/sda6", "/mnt/sda6",
311                 ensure    => "present",
312                 type      => "ext3",
313                 options   => [qw/noatime async/],
314                 on_change => sub { say "device mounted"; };
315          #
316          # mount persistent with entry in /etc/fstab
317
318          mount "/dev/sda6", "/mnt/sda6",
319                 ensure     => "persistent",
320                 type       => "ext3",
321                 options    => [qw/noatime async/],
322                 on_change  => sub { say "device mounted"; };
323
324          # to umount a device
325          mount "/dev/sda6", "/mnt/sda6",
326                 ensure => "absent";
327
328        };
329
330       In order to be more aligned with `mount` terminology, the previously
331       used `fs` option has been deprecated in favor of the `type` option. The
332       `fs` option is still supported and works as previously, but Rex prints
333       a warning if it is being used. There's also a warning if both `fs` and
334       `type` options are specified, and in this case `type` will be used.
335
336   umount($mount_point)
337       Unmount device.
338
339        task "umount", "server01", sub {
340          umount "/tmp";
341        };
342
343   glob($glob)
344        task "glob", "server1", sub {
345          my @files_with_p = grep { is_file($_) } glob("/etc/p*");
346        };
347
348       This command will not be reported.
349
350
351
352perl v5.30.0                      2019-07-24              Rex::Commands::Fs(3)