.\" Automatically generated by Pod::Man 4.09 (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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Rex::Commands::Fs 3pm"
.TH Rex::Commands::Fs 3pm "2018-02-01" "perl v5.26.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 \- Filesystem commands
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
With this module you can do file system tasks like creating a directory, deleting files, 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"
.ie n .SS "list_files(""/path"");"
.el .SS "list_files(``/path'');"
.IX Subsection "list_files(/path);"
This function list all entries (files, directories, ...) in a given directory and returns a 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.
.SS "ls($path)"
.IX Subsection "ls($path)"
Just an alias for \fIlist_files\fR
.ie n .SS "symlink($from, $to)"
.el .SS "symlink($from, \f(CW$to\fP)"
.IX Subsection "symlink($from, $to)"
This function will create a symlink 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
.ie n .SS "ln($from, $to)"
.el .SS "ln($from, \f(CW$to\fP)"
.IX Subsection "ln($from, $to)"
ln is an alias for \fIsymlink\fR
.SS "unlink($file)"
.IX Subsection "unlink($file)"
This function will remove the given file.
.PP
.Vb 3
\& task "unlink", "server01", sub {
\&   unlink("/tmp/testfile");
\& };
.Ve
.SS "rm($file)"
.IX Subsection "rm($file)"
This is an alias for unlink.
.SS "rmdir($dir)"
.IX Subsection "rmdir($dir)"
This function will remove the given directory.
.PP
.Vb 3
\& task "rmdir", "server01", sub {
\&   rmdir("/tmp");
\& };
.Ve
.PP
Since: 0.45 Please use the \fIfile()\fR resource instead.
.PP
.Vb 4
\& task "prepare", sub {
\&   file "/tmp",
\&     ensure => "absent";
\& };
.Ve
.SS "mkdir($newdir)"
.IX Subsection "mkdir($newdir)"
This function will create a new directory.
.PP
Since: 0.45 Please use the \fIfile()\fR resource instead.
.PP
.Vb 7
\& task "prepare", sub {
\&   file "/tmp",
\&     ensure => "directory",
\&     owner  => "root",
\&     group  => "root",
\&     mode   => 1777;
\& };
\& 
\& task "mkdir", "server01", sub {
\&   mkdir "/tmp";
\& 
\&   mkdir "/tmp",
\&     owner => "root",
\&     group => "root",
\&     mode => 1777;
\& };
.Ve
.ie n .SS "chown($owner, $file)"
.el .SS "chown($owner, \f(CW$file\fP)"
.IX Subsection "chown($owner, $file)"
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 \fIfile()\fR resource instead.
.ie n .SS "chgrp($group, $file)"
.el .SS "chgrp($group, \f(CW$file\fP)"
.IX Subsection "chgrp($group, $file)"
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 \fIfile()\fR resource instead.
.ie n .SS "chmod($mode, $file)"
.el .SS "chmod($mode, \f(CW$file\fP)"
.IX Subsection "chmod($mode, $file)"
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 \fIfile()\fR resource instead.
.SS "stat($file)"
.IX Subsection "stat($file)"
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.
.SS "is_file($file)"
.IX Subsection "is_file($file)"
This function tests if \f(CW$file\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.
.SS "is_dir($dir)"
.IX Subsection "is_dir($dir)"
This function tests if \f(CW$dir\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.
.SS "is_symlink($file)"
.IX Subsection "is_symlink($file)"
This function tests if \f(CW$file\fR is a symlink. 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.
.SS "is_readable($file)"
.IX Subsection "is_readable($file)"
This function tests if \f(CW$file\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.
.SS "is_writable($file)"
.IX Subsection "is_writable($file)"
This function tests if \f(CW$file\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.
.SS "is_writeable($file)"
.IX Subsection "is_writeable($file)"
This is only an alias for \fIis_writable\fR.
.PP
This command will not be reported.
.SS "readlink($link)"
.IX Subsection "readlink($link)"
This function returns the link endpoint if \f(CW$link\fR is a symlink. If \f(CW$link\fR is not a symlink it will die.
.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.
.ie n .SS "rename($old, $new)"
.el .SS "rename($old, \f(CW$new\fP)"
.IX Subsection "rename($old, $new)"
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
.ie n .SS "mv($old, $new)"
.el .SS "mv($old, \f(CW$new\fP)"
.IX Subsection "mv($old, $new)"
mv is an alias for \fIrename\fR.
.SS "chdir($newdir)"
.IX Subsection "chdir($newdir)"
This function will change the current workdirectory to \f(CW$newdir\fR. This function currently only works local.
.PP
.Vb 3
\& task "chdir", "server01", sub {
\&   chdir("/tmp");
\& };
.Ve
.PP
This command will not be reported.
.SS "cd($newdir)"
.IX Subsection "cd($newdir)"
This is an alias of \fIchdir\fR.
.SS "df([$device])"
.IX Subsection "df([$device])"
This function returns a hashRef reflecting the output of \fIdf\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.
.SS "du($path)"
.IX Subsection "du($path)"
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.
.ie n .SS "cp($source, $destination)"
.el .SS "cp($source, \f(CW$destination\fP)"
.IX Subsection "cp($source, $destination)"
cp will copy \f(CW$source\fR to \f(CW$destination\fR (it is recursive)
.PP
.Vb 3
\& task "cp", "server01", sub {
\&    cp("/var/www", "/var/www.old");
\& };
.Ve
.ie n .SS "mount($device, $mount_point, @options)"
.el .SS "mount($device, \f(CW$mount_point\fP, \f(CW@options\fP)"
.IX Subsection "mount($device, $mount_point, @options)"
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 `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.
.SS "umount($mount_point)"
.IX Subsection "umount($mount_point)"
Unmount device.
.PP
.Vb 3
\& task "umount", "server01", sub {
\&   umount "/tmp";
\& };
.Ve
.SS "glob($glob)"
.IX Subsection "glob($glob)"
.Vb 3
\& task "glob", "server1", sub {
\&   my @files_with_p = grep { is_file($_) } glob("/etc/p*");
\& };
.Ve
.PP
This command will not be reported.