.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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::File 3pm"
.TH Rex::Commands::File 3pm "2023-08-09" "perl v5.36.0" "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::File \- Transparent File Manipulation
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
With this module you can manipulate files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& task "read_passwd", "server01", sub {
\&   my $fh = file_read "/etc/passwd";
\&   for my $line ($fh\->read_all) {
\&     print $line;
\&   }
\&   $fh\->close;
\& };
\&
\& task "read_passwd2", "server01", sub {
\&   say cat "/etc/passwd";
\& };
\&
\&
\& task "write_passwd", "server01", sub {
\&   my $fh = file_write "/etc/passwd";
\&   $fh\->write("root:*:0:0:root user:/root:/bin/sh\en");
\&   $fh\->close;
\& };
\&
\& delete_lines_matching "/var/log/auth.log", matching => "root";
\& delete_lines_matching "/var/log/auth.log", matching => qr{Failed};
\& delete_lines_matching "/var/log/auth.log",
\&                matching => "root", qr{Failed}, "nobody";
\&
\& file "/path/on/the/remote/machine",
\&   source => "/path/on/local/machine";
\&
\& file "/path/on/the/remote/machine",
\&   content => "foo bar";
\&
\& file "/path/on/the/remote/machine",
\&   source => "/path/on/local/machine",
\&   owner  => "root",
\&   group  => "root",
\&   mode  => 400,
\&   on_change => sub { say shift, " was changed."; },
\&   on_no_change => sub { say shift, " wasn\*(Aqt changed."; };
.Ve
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.ie n .SS "template($file [, %params])"
.el .SS "template($file [, \f(CW%params\fP])"
.IX Subsection "template($file [, %params])"
Parse a template and return the content.
.PP
By default, it uses Rex::Template. If any of the template_ng or 1.3 (or newer) feature flag is enabled, then Rex::Template::NG is used instead of this module (recommended).
.PP
For more advanced functionality, you may use your favorite template engine via the set_template_function configuration option.
.PP
Template variables may be passed either as hash or a hash reference. The following calls are equivalent:
.PP
.Vb 1
\& template( $template, variable => value );
\&
\& template( $template, { variable => value } );
.Ve
.PP
\fIList of exposed template variables\fR
.IX Subsection "List of exposed template variables"
.PP
The following template variables are passed to the underlying templating engine, in order of precedence from low to high (variables of the same name are overridden by the next level aka \*(L"last one wins\*(R"):
.IP "task parameters" 4
.IX Item "task parameters"
All task parameters coming from the command line via \f(CW\*(C`rex taskname \-\-param=value\*(C'\fR, or from calling a task as a function, like \f(CW\*(C`taskname( { param => value } )\*(C'\fR.
.IP "resource parameters" 4
.IX Item "resource parameters"
All resource parameters as returned by \f(CW\*(C`Rex::Resource\->get_current_resource()\->get_all_parameters\*(C'\fR, when called inside a resource.
.IP "explicit template variables" 4
.IX Item "explicit template variables"
All manually specified, explicit template variables passed to \f(CW\*(C`template()\*(C'\fR.
.IP "system information" 4
.IX Item "system information"
The results from all available Rex::Hardware modules as returned by \f(CW\*(C`Rex::Hardware\->get(\*(AqAll\*(Aq)\*(C'\fR.
.Sp
Pass \f(CW\*(C`_\|_no_sys_info_\|_ => TRUE\*(C'\fR as a template variable to disable including system information:
.Sp
.Vb 1
\& my $content = template( $template, _\|_no_sys_info_\|_ => TRUE );
.Ve
.PP
\fIEmbedded templates\fR
.IX Subsection "Embedded templates"
.PP
Use \f(CW\*(C`_\|_DATA_\|_\*(C'\fR to embed templates at the end of the file. Prefix embedded template names with \f(CW\*(C`@\*(C'\fR. If embedding multiple templates, mark their end with \f(CW@end\fR.
.PP
Single template
.IX Subsection "Single template"
.PP
.Vb 4
\& my $content = template( \*(Aq@hello\*(Aq, name => \*(Aqworld\*(Aq ); # Hello, world!
\& _\|_DATA_\|_
\& @hello
\& Hello, <%= $name \-%>!
.Ve
.PP
Multiple templates
.IX Subsection "Multiple templates"
.PP
Use \f(CW@end\fR to separate multiple templates inside \f(CW\*(C`_\|_DATA_\|_\*(C'\fR.
.PP
.Vb 2
\& my $content     = template( \*(Aq@hello\*(Aq, name => \*(Aqworld\*(Aq ); # Hello, world!
\& my $alternative = template( \*(Aq@hi\*(Aq,    name => \*(Aqworld\*(Aq ); # Hi, world!
\&
\& _\|_DATA_\|_
\& @hello
\& Hello, <%= $name \-%>!
\& @end
\&
\& @hi
\& Hi, <%= $name \-%>!
\& @end
.Ve
.PP
\fIFile templates\fR
.IX Subsection "File templates"
.PP
.Vb 3
\& my $content = template("/files/templates/vhosts.tpl",
\&               name      => "test.lan",
\&               webmaster => \*(Aqwebmaster@test.lan\*(Aq);
.Ve
.PP
The file name specified is subject to \*(L"path_map\*(R" processing as documented
under the \fBfile()\fR function to resolve to a physical file name.
.PP
In addition to the \*(L"path_map\*(R" processing, if the \fB\-E\fR command line switch
is used to specify an environment name, existence of a file ending with
\&'.<env>' is checked and has precedence over the file without one, if it
exists. E.g. if rex is started as:
.PP
.Vb 1
\& $ rex \-E prod task1
.Ve
.PP
then in task1 defined as:
.PP
.Vb 3
\& task "task1", sub {
\&    say template("files/etc/ntpd.conf");
\& };
.Ve
.PP
will print the content of 'files/etc/ntpd.conf.prod' if it exists.
.PP
Note: the appended environment mechanism is always applied, after
the 'path_map' mechanism, if that is configured.
.ie n .SS "file($file_name [, %options])"
.el .SS "file($file_name [, \f(CW%options\fP])"
.IX Subsection "file($file_name [, %options])"
This function is the successor of \fIinstall file\fR. Please use this function to upload files to your server.
.PP
.Vb 3
\& task "prepare", "server1", "server2", sub {
\&   file "/file/on/remote/machine",
\&     source => "/file/on/local/machine";
\&
\&   file "/etc/hosts",
\&     content => template("templates/etc/hosts.tpl"),
\&     owner  => "user",
\&     group  => "group",
\&     mode   => 700,
\&     on_change => sub { say "Something was changed." },
\&     on_no_change => sub { say "Nothing has changed." };
\&
\&   file "/etc/motd",
\&     content => \`fortune\`;
\&
\&   file "/etc/named.conf",
\&     content    => template("templates/etc/named.conf.tpl"),
\&     no_overwrite => TRUE;  # this file will not be overwritten if already exists.
\&
\&   file "/etc/httpd/conf/httpd.conf",
\&     source => "/files/etc/httpd/conf/httpd.conf",
\&     on_change => sub { service httpd => "restart"; };
\&
\&   file "/etc/named.d",
\&     ensure => "directory",  # this will create a directory
\&     owner  => "root",
\&     group  => "root";
\&
\&   file "/etc/motd",
\&     ensure => "absent";   # this will remove the file or directory
\&
\& };
.Ve
.PP
The first parameter is either a string or an array reference. In the latter case the
function is called for all strings in the array. Therefore, the following constructs
are equivalent:
.PP
.Vb 2
\&  file \*(Aq/tmp/test1\*(Aq, ensure => \*(Aqdirectory\*(Aq;
\&  file \*(Aq/tmp/test2\*(Aq, ensure => \*(Aqdirectory\*(Aq;
\&
\&  file [ qw( /tmp/test1 /tmp/test2 ) ], ensure => \*(Aqdirectory\*(Aq; # use array ref
\&
\&  file [ glob(\*(Aq/tmp/test{1,2}\*(Aq) ], ensure => \*(Aqdirectory\*(Aq; # explicit glob call for array contents
.Ve
.PP
Use the glob carefully as \fBit can leak local filesystem information\fR (e.g. when using wildcards).
.PP
The \fIsource\fR is subject to a path resolution algorithm. This algorithm
can be configured using the \fIset\fR function to set the value of the
\&\fIpath_map\fR variable to a hash containing path prefixes as its keys.
The associated values are arrays listing the prefix replacements in order
of (decreasing) priority.
.PP
.Vb 4
\&  set "path_map", {
\&    "files/" => [ "files/{environment}/{hostname}/_root_/",
\&                  "files/{environment}/_root_/" ]
\&  };
.Ve
.PP
With this configuration, the file \*(L"files/etc/ntpd.conf\*(R" will be probed for
in the following locations:
.PP
.Vb 3
\& \- files/{environment}/{hostname}/_root_/etc/ntpd.conf
\& \- files/{environment}/_root_/etc/ntpd.conf
\& \- files/etc/ntpd.conf
.Ve
.PP
Furthermore, if a path prefix matches multiple prefix entries in 'path_map',
e.g. \*(L"files/etc/ntpd.conf\*(R" matching both \*(L"files/\*(R" and \*(L"files/etc/\*(R", the
longer matching prefix(es) have precedence over shorter ones. Note that
keys without a trailing slash (i.e. \*(L"files/etc\*(R") will be treated as having
a trailing slash when matching the prefix (\*(L"files/etc/\*(R").
.PP
If no file is found using the above procedure and \fIsource\fR is relative,
it will search from the location of your \fIRexfile\fR or the \fI.pm\fR file if
you use Perl packages.
.PP
All the possible variables ('{environment}', '{hostname}', ...) are documented
in the \s-1CMDB YAML\s0 documentation.
.PP
\fIHooks\fR
.IX Subsection "Hooks"
.PP
This function supports the following hooks:
.IP "before" 4
.IX Item "before"
This gets executed before anything is done. All original parameters are passed to it, including the applied defaults (\f(CW\*(C`ensure => \*(Aqpresent\*(Aq\*(C'\fR, resolved path for \f(CW\*(C`source\*(C'\fR).
.Sp
The return value of this hook overwrites the original parameters of the function call.
.IP "before_change" 4
.IX Item "before_change"
This gets executed right before the new file is written. All original parameters are passed to it, including the applied defaults (\f(CW\*(C`ensure => \*(Aqpresent\*(Aq\*(C'\fR, resolved path for \f(CW\*(C`source\*(C'\fR).
.IP "after_change" 4
.IX Item "after_change"
This gets executed right after the file is written. All original parameters, including the applied defaults (\f(CW\*(C`ensure => \*(Aqpresent\*(Aq\*(C'\fR, resolved path for \f(CW\*(C`source\*(C'\fR), and any returned results are passed to it.
.IP "after" 4
.IX Item "after"
This gets executed right before the \f(CW\*(C`file()\*(C'\fR function returns. All original parameters, including the applied defaults (\f(CW\*(C`ensure => \*(Aqpresent\*(Aq\*(C'\fR, resolved path for \f(CW\*(C`source\*(C'\fR), and any returned results are passed to it.
.SS "file_write($file_name)"
.IX Subsection "file_write($file_name)"
This function opens a file for writing (it will truncate the file if it already exists). It returns a Rex::FS::File object on success.
.PP
On failure it will die.
.PP
.Vb 4
\& my $fh;
\& eval {
\&   $fh = file_write("/etc/groups");
\& };
\&
\& # catch an error
\& if($@) {
\&   print "An error occurred. $@.\en";
\& }
\&
\& # work with the filehandle
\& $fh\->write("...");
\& $fh\->close;
.Ve
.SS "file_append($file_name)"
.IX Subsection "file_append($file_name)"
.SS "file_read($file_name)"
.IX Subsection "file_read($file_name)"
This function opens a file for reading. It returns a Rex::FS::File object on success.
.PP
On failure it will die.
.PP
.Vb 4
\& my $fh;
\& eval {
\&   $fh = file_read("/etc/groups");
\& };
\&
\& # catch an error
\& if($@) {
\&   print "An error occurred. $@.\en";
\& }
\&
\& # work with the filehandle
\& my $content = $fh\->read_all;
\& $fh\->close;
.Ve
.SS "cat($file_name)"
.IX Subsection "cat($file_name)"
This function returns the complete content of \f(CW$file_name\fR as a string.
.PP
.Vb 1
\& print cat "/etc/passwd";
.Ve
.ie n .SS "delete_lines_matching($file, $regexp)"
.el .SS "delete_lines_matching($file, \f(CW$regexp\fP)"
.IX Subsection "delete_lines_matching($file, $regexp)"
Delete lines that match \f(CW$regexp\fR in \f(CW$file\fR.
.PP
.Vb 3
\& task "clean\-logs", sub {
\&    delete_lines_matching "/var/log/auth.log" => "root";
\& };
.Ve
.ie n .SS "delete_lines_according_to($search, $file [, @options])"
.el .SS "delete_lines_according_to($search, \f(CW$file\fP [, \f(CW@options\fP])"
.IX Subsection "delete_lines_according_to($search, $file [, @options])"
This is the successor of the \fBdelete_lines_matching()\fR function. This function also allows the usage of on_change and on_no_change hooks.
.PP
It will search for \f(CW$search\fR in \f(CW$file\fR and remove the found lines. If on_change hook is present it will execute this if the file was changed.
.PP
.Vb 6
\& task "cleanup", "server1", sub {
\&   delete_lines_according_to qr{^foo:}, "/etc/passwd",
\&    on_change => sub {
\&      say "removed user foo.";
\&    };
\& };
.Ve
.ie n .SS "append_if_no_such_line($file, $new_line [, @regexp])"
.el .SS "append_if_no_such_line($file, \f(CW$new_line\fP [, \f(CW@regexp\fP])"
.IX Subsection "append_if_no_such_line($file, $new_line [, @regexp])"
Append \f(CW$new_line\fR to \f(CW$file\fR if none in \f(CW@regexp\fR is found. If no regexp is
supplied, the line is appended unless there is already an identical line
in \f(CW$file\fR.
.PP
.Vb 3
\& task "add\-group", sub {
\&   append_if_no_such_line "/etc/groups", "mygroup:*:100:myuser1,myuser2", on_change => sub { service sshd => "restart"; };
\& };
.Ve
.PP
Since 0.42 you can use named parameters as well
.PP
.Vb 7
\& task "add\-group", sub {
\&   append_if_no_such_line "/etc/groups",
\&     line  => "mygroup:*:100:myuser1,myuser2",
\&     regexp => qr{^mygroup},
\&     on_change => sub {
\&                say "file was changed, do something.";
\&              };
\&
\&   append_if_no_such_line "/etc/groups",
\&     line  => "mygroup:*:100:myuser1,myuser2",
\&     regexp => [qr{^mygroup:}, qr{^ourgroup:}]; # this is an OR
\& };
.Ve
.ie n .SS "append_or_amend_line($file, $line [, @regexp])"
.el .SS "append_or_amend_line($file, \f(CW$line\fP [, \f(CW@regexp\fP])"
.IX Subsection "append_or_amend_line($file, $line [, @regexp])"
Similar to append_if_no_such_line, but if the line in the regexp is
found, it will be updated. Otherwise, it will be appended.
.PP
.Vb 11
\& task "update\-group", sub {
\&   append_or_amend_line "/etc/groups",
\&     line  => "mygroup:*:100:myuser3,myuser4",
\&     regexp => qr{^mygroup},
\&     on_change => sub {
\&       say "file was changed, do something.";
\&     },
\&     on_no_change => sub {
\&       say "file was not changed, do something.";
\&     };
\& };
.Ve
.ie n .SS "extract($file [, %options])"
.el .SS "extract($file [, \f(CW%options\fP])"
.IX Subsection "extract($file [, %options])"
This function extracts a file. The target directory optionally specified with the `to` option will be created automatically.
.PP
Supported formats are .box, .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .zip, .gz, .bz2, .war, .jar.
.PP
.Vb 5
\& task prepare => sub {
\&   extract "/tmp/myfile.tar.gz",
\&    owner => "root",
\&    group => "root",
\&    to   => "/etc";
\&
\&   extract "/tmp/foo.tgz",
\&    type => "tgz",
\&    mode => "g+rwX";
\& };
.Ve
.PP
Can use the type=> option if the file suffix has been changed. (types are tar, tgz, tbz, zip, gz, bz2)
.ie n .SS "sed($search, $replace, $file [, %options])"
.el .SS "sed($search, \f(CW$replace\fP, \f(CW$file\fP [, \f(CW%options\fP])"
.IX Subsection "sed($search, $replace, $file [, %options])"
Search some string in a file and replace it.
.PP
.Vb 3
\& task sar => sub {
\&   # this will work line by line
\&   sed qr{search}, "replace", "/var/log/auth.log";
\&
\&   # to use it in a multiline way
\&   sed qr{search}, "replace", "/var/log/auth.log",
\&    multiline => TRUE;
\& };
.Ve
.PP
Like similar file management commands, it also supports \f(CW\*(C`on_change\*(C'\fR and \f(CW\*(C`on_no_change\*(C'\fR hooks.