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

NAME

6       Rex::Commands::Fs - File system commands
7

DESCRIPTION

9       With this module you can do file system tasks like creating
10       directories, deleting or 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   Changing content
40       These commands are supposed to change the contents of the file system.
41
42       symlink($from, $to)
43
44       This function will create a symbolic link from $from to $to.
45
46        task "symlink", "server01", sub {
47          symlink("/var/www/versions/1.0.0", "/var/www/html");
48        };
49
50       ln($from, $to)
51
52       "ln" is an alias for "symlink"
53
54       unlink($file)
55
56       This function will remove the given $file.
57
58        task "unlink", "server01", sub {
59          unlink("/tmp/testfile");
60        };
61
62       rm($file)
63
64       This is an alias for "unlink".
65
66       rmdir($dir)
67
68       This function will remove the given directory.
69
70        task "rmdir", "server01", sub {
71          rmdir("/tmp");
72        };
73
74       With Rex-0.45 and newer, please use the file resource instead.
75
76        task "prepare", sub {
77          file "/tmp",
78            ensure => "absent";
79        };
80
81       mkdir($newdir)
82
83       This function will create a new directory.
84
85       The following options are supported:
86
87       •   owner
88
89       •   group
90
91       •   mode
92
93       •   on_change
94
95       With Rex-0.45 and newer, please use the file resource instead.
96
97        task "prepare", sub {
98          file "/tmp",
99            ensure => "directory",
100            owner  => "root",
101            group  => "root",
102            mode   => 1777;
103        };
104
105       Direct usage:
106
107        task "mkdir", "server01", sub {
108          mkdir "/tmp";
109
110          mkdir "/tmp",
111            owner => "root",
112            group => "root",
113            mode => 1777;
114        };
115
116       chown($owner, $path)
117
118       Change the owner of a file or a directory.
119
120        chown "www-data", "/var/www/html";
121
122        chown "www-data", "/var/www/html",
123                       recursive => 1;
124
125       This command will not be reported.
126
127       If you want to use reports, please use the file resource instead.
128
129       chgrp($group, $path)
130
131       Change the group of a file or a directory.
132
133        chgrp "nogroup", "/var/www/html";
134
135        chgrp "nogroup", "/var/www/html",
136                     recursive => 1;
137
138       This command will not be reported.
139
140       If you want to use reports, please use the file resource instead.
141
142       chmod($mode, $path)
143
144       Change the permissions of a file or a directory.
145
146        chmod 755, "/var/www/html";
147
148        chmod 755, "/var/www/html",
149                 recursive => 1;
150
151       This command will not be reported.
152
153       If you want to use reports, please use the file resource instead.
154
155       rename($old, $new)
156
157       This function will rename $old to $new. Will return 1 on success and 0
158       on failure.
159
160        task "rename", "server01", sub {
161          rename("/tmp/old", "/tmp/new");
162        };
163
164       mv($old, $new)
165
166       "mv" is an alias for "rename".
167
168       cp($source, $destination)
169
170       "cp" will copy $source to $destination recursively.
171
172        task "cp", "server01", sub {
173           cp("/var/www", "/var/www.old");
174        };
175
176   Not changing content
177       These commands should not change the contents of the file system.
178
179       list_files("/path");
180
181       This function lists all entries (files, directories, ...) in a given
182       directory and returns them as an array.
183
184        task "ls-etc", "server01", sub {
185          my @tmp_files = grep { /\.tmp$/ } list_files("/etc");
186        };
187
188       This command will not be reported.
189
190       ls($path)
191
192       Just an alias for "list_files".
193
194       stat($file)
195
196       This function will return a hash with the following information about a
197       file or directory:
198
199       mode
200       size
201       uid
202       gid
203       atime
204       mtime
205
206        task "stat", "server01", sub {
207          my %file_stat = stat("/etc/passwd");
208        };
209
210       This command will not be reported.
211
212       is_file($path)
213
214       This function tests if $path is a file. Returns 1 if true, 0 if false.
215
216        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
225       This command will not be reported.
226
227       is_dir($path)
228
229       This function tests if $path is a directory. Returns 1 if true, 0 if
230       false.
231
232        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
241       This command will not be reported.
242
243       is_symlink($path)
244
245       This function tests if $path is a symbolic link. Returns 1 if true, 0
246       if false.
247
248        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
257       This command will not be reported.
258
259       is_readable($path)
260
261       This function tests if $path is readable. It returns 1 if true, 0 if
262       false.
263
264        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
273       This command will not be reported.
274
275       is_writable($path)
276
277       This function tests if $path is writable. It returns 1 if true, 0 if
278       false.
279
280        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
289       This command will not be reported.
290
291       is_writeable($file)
292
293       This is only an alias for "is_writable".
294
295       readlink($link)
296
297       If $link is a symbolic link, returns the path it resolves to, and
298       die()s otherwise.
299
300        task "islink", "server01", sub {
301          my $link;
302          eval {
303            $link = readlink("/tmp/testlink");
304          };
305
306          say "this is a link" if($link);
307        };
308
309       This command will not be reported.
310
311       chdir($newdir)
312
313       This function will change the working directory to $newdir. This
314       function currently works only locally.
315
316        task "chdir", "server01", sub {
317          chdir("/tmp");
318        };
319
320       This command will not be reported.
321
322       cd($newdir)
323
324       This is an alias of "chdir".
325
326       df([$device])
327
328       This function returns a hash reference which reflects the output of
329       "df".
330
331        task "df", "server01", sub {
332           my $df = df();
333           my $df_on_sda1 = df("/dev/sda1");
334        };
335
336       This command will not be reported.
337
338       du($path)
339
340       Returns the disk usage of $path.
341
342        task "du", "server01", sub {
343          say "size of /var/www: " . du("/var/www");
344        };
345
346       This command will not be reported.
347
348       mount($device, $mount_point, @options)
349
350       Mount devices.
351
352        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
362          mount "/dev/sda6", "/mnt/sda6",
363                 ensure     => "persistent",
364                 type       => "ext3",
365                 options    => [qw/noatime async/],
366                 on_change  => sub { say "device mounted"; };
367
368          # to umount a device
369          mount "/dev/sda6", "/mnt/sda6",
370                 ensure => "absent";
371
372        };
373
374       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
380       umount($mount_point)
381
382       Unmount device.
383
384        task "umount", "server01", sub {
385          umount "/tmp";
386        };
387
388       glob($glob)
389
390       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
393        task "glob", "server1", sub {
394          my @files_with_p = grep { is_file($_) } glob("/etc/p*");
395        };
396
397       This command will not be reported.
398
399
400
401perl v5.38.0                      2023-08-07              Rex::Commands::Fs(3)
Impressum