Provided by: rex_1.13.4-1_all 
NAME
Rex::Commands::Fs - File system commands
DESCRIPTION
With this module you can do file system tasks like creating directories, deleting or
moving files, and more.
SYNOPSIS
my @files = list_files "/etc";
unlink("/tmp/file");
rmdir("/tmp");
mkdir("/tmp");
my %stat = stat("/etc/passwd");
my $link = readlink("/path/to/a/link");
symlink("/source", "/dest");
rename("oldname", "newname");
chdir("/tmp");
is_file("/etc/passwd");
is_dir("/etc");
is_writeable("/tmp");
is_writable("/tmp");
chmod 755, "/tmp";
chown "user", "/tmp";
chgrp "group", "/tmp";
EXPORTED FUNCTIONS
Changing content
These commands are supposed to change the contents of the file system.
symlink($from, $to)
This function will create a symbolic link from $from to $to.
task "symlink", "server01", sub {
symlink("/var/www/versions/1.0.0", "/var/www/html");
};
ln($from, $to)
"ln" is an alias for "symlink"
unlink($file)
This function will remove the given $file.
task "unlink", "server01", sub {
unlink("/tmp/testfile");
};
rm($file)
This is an alias for "unlink".
rmdir($dir)
This function will remove the given directory.
task "rmdir", "server01", sub {
rmdir("/tmp");
};
With Rex-0.45 and newer, please use the file resource instead.
task "prepare", sub {
file "/tmp",
ensure => "absent";
};
mkdir($newdir)
This function will create a new directory.
The following options are supported:
• owner
• group
• mode
• on_change
With Rex-0.45 and newer, please use the file resource instead.
task "prepare", sub {
file "/tmp",
ensure => "directory",
owner => "root",
group => "root",
mode => 1777;
};
Direct usage:
task "mkdir", "server01", sub {
mkdir "/tmp";
mkdir "/tmp",
owner => "root",
group => "root",
mode => 1777;
};
chown($owner, $path)
Change the owner of a file or a directory.
chown "www-data", "/var/www/html";
chown "www-data", "/var/www/html",
recursive => 1;
This command will not be reported.
If you want to use reports, please use the file resource instead.
chgrp($group, $path)
Change the group of a file or a directory.
chgrp "nogroup", "/var/www/html";
chgrp "nogroup", "/var/www/html",
recursive => 1;
This command will not be reported.
If you want to use reports, please use the file resource instead.
chmod($mode, $path)
Change the permissions of a file or a directory.
chmod 755, "/var/www/html";
chmod 755, "/var/www/html",
recursive => 1;
This command will not be reported.
If you want to use reports, please use the file resource instead.
rename($old, $new)
This function will rename $old to $new. Will return 1 on success and 0 on failure.
task "rename", "server01", sub {
rename("/tmp/old", "/tmp/new");
};
mv($old, $new)
"mv" is an alias for "rename".
cp($source, $destination)
"cp" will copy $source to $destination recursively.
task "cp", "server01", sub {
cp("/var/www", "/var/www.old");
};
Not changing content
These commands should not change the contents of the file system.
list_files("/path");
This function lists all entries (files, directories, ...) in a given directory and returns
them as an array.
task "ls-etc", "server01", sub {
my @tmp_files = grep { /\.tmp$/ } list_files("/etc");
};
This command will not be reported.
ls($path)
Just an alias for "list_files".
stat($file)
This function will return a hash with the following information about a file or directory:
mode
size
uid
gid
atime
mtime
task "stat", "server01", sub {
my %file_stat = stat("/etc/passwd");
};
This command will not be reported.
is_file($path)
This function tests if $path is a file. Returns 1 if true, 0 if false.
task "isfile", "server01", sub {
if( is_file("/etc/passwd") ) {
say "it is a file.";
}
else {
say "hm, this is not a file.";
}
};
This command will not be reported.
is_dir($path)
This function tests if $path is a directory. Returns 1 if true, 0 if false.
task "isdir", "server01", sub {
if( is_dir("/etc") ) {
say "it is a directory.";
}
else {
say "hm, this is not a directory.";
}
};
This command will not be reported.
is_symlink($path)
This function tests if $path is a symbolic link. Returns 1 if true, 0 if false.
task "issym", "server01", sub {
if( is_symlink("/etc/foo.txt") ) {
say "it is a symlink.";
}
else {
say "hm, this is not a symlink.";
}
};
This command will not be reported.
is_readable($path)
This function tests if $path is readable. It returns 1 if true, 0 if false.
task "readable", "server01", sub {
if( is_readable("/etc/passwd") ) {
say "passwd is readable";
}
else {
say "not readable.";
}
};
This command will not be reported.
is_writable($path)
This function tests if $path is writable. It returns 1 if true, 0 if false.
task "writable", "server01", sub {
if( is_writable("/etc/passwd") ) {
say "passwd is writable";
}
else {
say "not writable.";
}
};
This command will not be reported.
is_writeable($file)
This is only an alias for "is_writable".
readlink($link)
If $link is a symbolic link, returns the path it resolves to, and "die()"s otherwise.
task "islink", "server01", sub {
my $link;
eval {
$link = readlink("/tmp/testlink");
};
say "this is a link" if($link);
};
This command will not be reported.
chdir($newdir)
This function will change the working directory to $newdir. This function currently works
only locally.
task "chdir", "server01", sub {
chdir("/tmp");
};
This command will not be reported.
cd($newdir)
This is an alias of "chdir".
df([$device])
This function returns a hash reference which reflects the output of "df".
task "df", "server01", sub {
my $df = df();
my $df_on_sda1 = df("/dev/sda1");
};
This command will not be reported.
du($path)
Returns the disk usage of $path.
task "du", "server01", sub {
say "size of /var/www: " . du("/var/www");
};
This command will not be reported.
mount($device, $mount_point, @options)
Mount devices.
task "mount", "server01", sub {
mount "/dev/sda5", "/tmp";
mount "/dev/sda6", "/mnt/sda6",
ensure => "present",
type => "ext3",
options => [qw/noatime async/],
on_change => sub { say "device mounted"; };
#
# mount persistent with entry in /etc/fstab
mount "/dev/sda6", "/mnt/sda6",
ensure => "persistent",
type => "ext3",
options => [qw/noatime async/],
on_change => sub { say "device mounted"; };
# to umount a device
mount "/dev/sda6", "/mnt/sda6",
ensure => "absent";
};
In order to be more aligned with "mount" terminology, the previously used "fs" option has
been deprecated in favor of the "type" option. The "fs" option is still supported and
works as previously, but Rex prints a warning if it is being used. There's also a warning
if both "fs" and "type" options are specified, and in this case "type" will be used.
umount($mount_point)
Unmount device.
task "umount", "server01", sub {
umount "/tmp";
};
glob($glob)
Returns the list of filename expansions for $glob as Perl's built-in glob
<https://perldoc.perl.org/functions/glob.html> would do.
task "glob", "server1", sub {
my @files_with_p = grep { is_file($_) } glob("/etc/p*");
};
This command will not be reported.