.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Rex::Commands::Fs 3pm"
.TH Rex::Commands::Fs 3pm "2020-09-18" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Rex::Commands::Fs \- File system commands
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
With this module you can do file system tasks like creating directories, deleting or moving files, and more.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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";
.Ve
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.SS "Changing content"
.IX Subsection "Changing content"
These commands are supposed to change the contents of the file system.
.PP
\fIsymlink($from, \f(CI$to\fI)\fR
.IX Subsection "symlink($from, $to)"
.PP
This function will create a symbolic link from \f(CW$from\fR to \f(CW$to\fR.
.PP
.Vb 3
\& task "symlink", "server01", sub {
\&   symlink("/var/www/versions/1.0.0", "/var/www/html");
\& };
.Ve
.PP
\fIln($from, \f(CI$to\fI)\fR
.IX Subsection "ln($from, $to)"
.PP
\&\f(CW\*(C`ln\*(C'\fR is an alias for \f(CW\*(C`symlink\*(C'\fR
.PP
\fIunlink($file)\fR
.IX Subsection "unlink($file)"
.PP
This function will remove the given \f(CW$file\fR.
.PP
.Vb 3
\& task "unlink", "server01", sub {
\&   unlink("/tmp/testfile");
\& };
.Ve
.PP
\fIrm($file)\fR
.IX Subsection "rm($file)"
.PP
This is an alias for \f(CW\*(C`unlink\*(C'\fR.
.PP
\fIrmdir($dir)\fR
.IX Subsection "rmdir($dir)"
.PP
This function will remove the given directory.
.PP
.Vb 3
\& task "rmdir", "server01", sub {
\&   rmdir("/tmp");
\& };
.Ve
.PP
With Rex\-0.45 and newer, please use the file resource instead.
.PP
.Vb 4
\& task "prepare", sub {
\&   file "/tmp",
\&     ensure => "absent";
\& };
.Ve
.PP
\fImkdir($newdir)\fR
.IX Subsection "mkdir($newdir)"
.PP
This function will create a new directory.
.PP
The following options are supported:
.IP "\(bu" 4
owner
.IP "\(bu" 4
group
.IP "\(bu" 4
mode
.IP "\(bu" 4
on_change
.PP
With Rex\-0.45 and newer, please use the file resource instead.
.PP
.Vb 7
\& task "prepare", sub {
\&   file "/tmp",
\&     ensure => "directory",
\&     owner  => "root",
\&     group  => "root",
\&     mode   => 1777;
\& };
.Ve
.PP
Direct usage:
.PP
.Vb 2
\& task "mkdir", "server01", sub {
\&   mkdir "/tmp";
\& 
\&   mkdir "/tmp",
\&     owner => "root",
\&     group => "root",
\&     mode => 1777;
\& };
.Ve
.PP
\fIchown($owner, \f(CI$path\fI)\fR
.IX Subsection "chown($owner, $path)"
.PP
Change the owner of a file or a directory.
.PP
.Vb 1
\& chown "www\-data", "/var/www/html";
\& 
\& chown "www\-data", "/var/www/html",
\&                recursive => 1;
.Ve
.PP
This command will not be reported.
.PP
If you want to use reports, please use the file resource instead.
.PP
\fIchgrp($group, \f(CI$path\fI)\fR
.IX Subsection "chgrp($group, $path)"
.PP
Change the group of a file or a directory.
.PP
.Vb 1
\& chgrp "nogroup", "/var/www/html";
\& 
\& chgrp "nogroup", "/var/www/html",
\&              recursive => 1;
.Ve
.PP
This command will not be reported.
.PP
If you want to use reports, please use the file resource instead.
.PP
\fIchmod($mode, \f(CI$path\fI)\fR
.IX Subsection "chmod($mode, $path)"
.PP
Change the permissions of a file or a directory.
.PP
.Vb 1
\& chmod 755, "/var/www/html";
\& 
\& chmod 755, "/var/www/html",
\&          recursive => 1;
.Ve
.PP
This command will not be reported.
.PP
If you want to use reports, please use the file resource instead.
.PP
\fIrename($old, \f(CI$new\fI)\fR
.IX Subsection "rename($old, $new)"
.PP
This function will rename \f(CW$old\fR to \f(CW$new\fR. Will return 1 on success and 0 on failure.
.PP
.Vb 3
\& task "rename", "server01", sub {
\&   rename("/tmp/old", "/tmp/new");
\& };
.Ve
.PP
\fImv($old, \f(CI$new\fI)\fR
.IX Subsection "mv($old, $new)"
.PP
\&\f(CW\*(C`mv\*(C'\fR is an alias for \f(CW\*(C`rename\*(C'\fR.
.PP
\fIcp($source, \f(CI$destination\fI)\fR
.IX Subsection "cp($source, $destination)"
.PP
\&\f(CW\*(C`cp\*(C'\fR will copy \f(CW$source\fR to \f(CW$destination\fR recursively.
.PP
.Vb 3
\& task "cp", "server01", sub {
\&    cp("/var/www", "/var/www.old");
\& };
.Ve
.SS "Not changing content"
.IX Subsection "Not changing content"
These commands should not change the contents of the file system.
.PP
\fIlist_files(\*(L"/path\*(R");\fR
.IX Subsection "list_files(/path);"
.PP
This function lists all entries (files, directories, ...) in a given directory and returns them as an array.
.PP
.Vb 3
\& task "ls\-etc", "server01", sub {
\&   my @tmp_files = grep { /\e.tmp$/ } list_files("/etc");
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIls($path)\fR
.IX Subsection "ls($path)"
.PP
Just an alias for \f(CW\*(C`list_files\*(C'\fR.
.PP
\fIstat($file)\fR
.IX Subsection "stat($file)"
.PP
This function will return a hash with the following information about a file or directory:
.IP "mode" 4
.IX Item "mode"
.PD 0
.IP "size" 4
.IX Item "size"
.IP "uid" 4
.IX Item "uid"
.IP "gid" 4
.IX Item "gid"
.IP "atime" 4
.IX Item "atime"
.IP "mtime" 4
.IX Item "mtime"
.PD
.PP
.Vb 3
\& task "stat", "server01", sub {
\&   my %file_stat = stat("/etc/passwd");
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIis_file($path)\fR
.IX Subsection "is_file($path)"
.PP
This function tests if \f(CW$path\fR is a file. Returns 1 if true, 0 if false.
.PP
.Vb 8
\& task "isfile", "server01", sub {
\&   if( is_file("/etc/passwd") ) {
\&     say "it is a file.";
\&   }
\&   else {
\&     say "hm, this is not a file.";
\&   }
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIis_dir($path)\fR
.IX Subsection "is_dir($path)"
.PP
This function tests if \f(CW$path\fR is a directory. Returns 1 if true, 0 if false.
.PP
.Vb 8
\& task "isdir", "server01", sub {
\&   if( is_dir("/etc") ) {
\&     say "it is a directory.";
\&   }
\&   else {
\&     say "hm, this is not a directory.";
\&   }
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIis_symlink($path)\fR
.IX Subsection "is_symlink($path)"
.PP
This function tests if \f(CW$path\fR is a symbolic link. Returns 1 if true, 0 if false.
.PP
.Vb 8
\& task "issym", "server01", sub {
\&   if( is_symlink("/etc/foo.txt") ) {
\&     say "it is a symlink.";
\&   }
\&   else {
\&     say "hm, this is not a symlink.";
\&   }
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIis_readable($path)\fR
.IX Subsection "is_readable($path)"
.PP
This function tests if \f(CW$path\fR is readable. It returns 1 if true, 0 if false.
.PP
.Vb 8
\& task "readable", "server01", sub {
\&   if( is_readable("/etc/passwd") ) {
\&     say "passwd is readable";
\&   }
\&   else {
\&     say "not readable.";
\&   }
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIis_writable($path)\fR
.IX Subsection "is_writable($path)"
.PP
This function tests if \f(CW$path\fR is writable. It returns 1 if true, 0 if false.
.PP
.Vb 8
\& task "writable", "server01", sub {
\&   if( is_writable("/etc/passwd") ) {
\&     say "passwd is writable";
\&   }
\&   else {
\&     say "not writable.";
\&   }
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIis_writeable($file)\fR
.IX Subsection "is_writeable($file)"
.PP
This is only an alias for \f(CW\*(C`is_writable\*(C'\fR.
.PP
\fIreadlink($link)\fR
.IX Subsection "readlink($link)"
.PP
If \f(CW$link\fR is a symbolic link, returns the path it resolves to, and \f(CW\*(C`die()\*(C'\fRs otherwise.
.PP
.Vb 5
\& task "islink", "server01", sub {
\&   my $link;
\&   eval {
\&     $link = readlink("/tmp/testlink");
\&   };
\& 
\&   say "this is a link" if($link);
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIchdir($newdir)\fR
.IX Subsection "chdir($newdir)"
.PP
This function will change the working directory to \f(CW$newdir\fR. This function currently works only locally.
.PP
.Vb 3
\& task "chdir", "server01", sub {
\&   chdir("/tmp");
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIcd($newdir)\fR
.IX Subsection "cd($newdir)"
.PP
This is an alias of \f(CW\*(C`chdir\*(C'\fR.
.PP
\fIdf([$device])\fR
.IX Subsection "df([$device])"
.PP
This function returns a hash reference which reflects the output of \f(CW\*(C`df\*(C'\fR.
.PP
.Vb 4
\& task "df", "server01", sub {
\&    my $df = df();
\&    my $df_on_sda1 = df("/dev/sda1");
\& };
.Ve
.PP
This command will not be reported.
.PP
\fIdu($path)\fR
.IX Subsection "du($path)"
.PP
Returns the disk usage of \f(CW$path\fR.
.PP
.Vb 3
\& task "du", "server01", sub {
\&   say "size of /var/www: " . du("/var/www");
\& };
.Ve
.PP
This command will not be reported.
.PP
\fImount($device, \f(CI$mount_point\fI, \f(CI@options\fI)\fR
.IX Subsection "mount($device, $mount_point, @options)"
.PP
Mount devices.
.PP
.Vb 9
\& 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";
\& 
\& };
.Ve
.PP
In order to be more aligned with \f(CW\*(C`mount\*(C'\fR terminology, the previously used \f(CW\*(C`fs\*(C'\fR option has been deprecated in favor of the \f(CW\*(C`type\*(C'\fR option. The \f(CW\*(C`fs\*(C'\fR 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 \f(CW\*(C`fs\*(C'\fR and \f(CW\*(C`type\*(C'\fR options are specified, and in this case \f(CW\*(C`type\*(C'\fR will be used.
.PP
\fIumount($mount_point)\fR
.IX Subsection "umount($mount_point)"
.PP
Unmount device.
.PP
.Vb 3
\& task "umount", "server01", sub {
\&   umount "/tmp";
\& };
.Ve
.PP
\fIglob($glob)\fR
.IX Subsection "glob($glob)"
.PP
Returns the list of filename expansions for \f(CW$glob\fR as Perl's built-in glob <https://perldoc.perl.org/functions/glob.html> would do.
.PP
.Vb 3
\& task "glob", "server1", sub {
\&   my @files_with_p = grep { is_file($_) } glob("/etc/p*");
\& };
.Ve
.PP
This command will not be reported.