Rex::C...s::File(3pm)

💖 Rex::Commands::File(3pm) 💖

okay bestie, welcome to the Rex::Commands::File page 💅 it lives in the User Contributed Perl Documentation section of the manual, and it's literally all about Transparent File Manipulation. yes it's long. no we're not skipping anything. grab a snack 🍓

---

✨ NAME ✨

Rex::Commands::File — Transparent File Manipulation. that's the whole vibe. 🎀

🦋 DESCRIPTION 🦋

With this module you can manipulate files. that's it, that's the sentence, and honestly? iconic. short. ate. 🔥

🌸 SYNOPSIS 🌸

here's the whole menu of what this thing can do, verbatim, no cap:

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\n");
  $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't changed."; };

---

👑 EXPORTED FUNCTIONS 👑

this is the main character section, bestie. every function here is getting its moment.

🧚 template($file [, %params])

Parse a template and return the content. that's the job. 💫

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). so like… turn that on, fr fr.

For more advanced functionality, you may use your favorite template engine via the set_template_function configuration option.

Template variables may be passed either as hash or a hash reference. The following calls are equivalent:

template( $template, variable => value );

template( $template, { variable => value } );

🌈 List of exposed template variables

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 "last one wins"):

• task parameters — all task parameters coming from the command line via rex taskname --param=value, or from calling a task as a function, like taskname( { param => value } ).
• resource parameters — all resource parameters as returned by Rex::Resource->get_current_resource()->get_all_parameters, when called inside a resource.
• explicit template variables — all manually specified, explicit template variables passed to template().
• system information — the results from all available Rex::Hardware modules as returned by Rex::Hardware->get('All').

pass __no_sys_info__ => TRUE as a template variable to disable including system information, like this:

my $content = template( $template, __no_sys_info__ => TRUE );

🎀 Embedded templates

Use __DATA__ to embed templates at the end of the file. Prefix embedded template names with @. If embedding multiple templates, mark their end with @end.

Single template

my $content = template( '@hello', name => 'world' ); # Hello, world!
__DATA__
@hello
Hello, <%= $name -%>!

Multiple templates

Use @end to separate multiple templates inside __DATA__.

my $content     = template( '@hello', name => 'world' ); # Hello, world!
my $alternative = template( '@hi',    name => 'world' ); # Hi, world!

__DATA__
@hello
Hello, <%= $name -%>!
@end

@hi
Hi, <%= $name -%>!
@end

File templates

my $content = template("/files/templates/vhosts.tpl",
              name      => "test.lan",
              webmaster => 'webmaster@test.lan');

The file name specified is subject to path_map processing as documented under the file() function to resolve to a physical file name. 👀

In addition to the path_map processing, if the -E 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:

$ rex -E prod task1

then in task1 defined as:

task "task1", sub {
   say template("files/etc/ntpd.conf");
};

will print the content of files/etc/ntpd.conf.prod if it exists.

Note: the appended environment mechanism is always applied, after the path_map mechanism, if that is configured.

💜 file($file_name [, %options])

This function is the successor of install file. Please use this function to upload files to your server. periodt. ✨

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

};

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:

file '/tmp/test1', ensure => 'directory';
file '/tmp/test2', ensure => 'directory';

file [ qw( /tmp/test1 /tmp/test2 ) ], ensure => 'directory'; # use array ref

file [ glob('/tmp/test{1,2}') ], ensure => 'directory'; # explicit glob call for array contents

⚠️ Use the glob carefully as it can leak local filesystem information (e.g. when using wildcards). like, genuinely. be careful bestie. 🙈

The source is subject to a path resolution algorithm. This algorithm can be configured using the set function to set the value of the path_map variable to a hash containing path prefixes as its keys. The associated values are arrays listing the prefix replacements in order of (decreasing) priority.

set "path_map", {
  "files/" => [ "files/{environment}/{hostname}/_root_/",
                "files/{environment}/_root_/" ]
};

With this configuration, the file files/etc/ntpd.conf will be probed for in the following locations:

• files/{environment}/{hostname}/_root_/etc/ntpd.conf
• files/{environment}/_root_/etc/ntpd.conf
• files/etc/ntpd.conf

Furthermore, if a path prefix matches multiple prefix entries in path_map, e.g. files/etc/ntpd.conf matching both files/ and files/etc/, the longer matching prefix(es) have precedence over shorter ones. Note that keys without a trailing slash (i.e. files/etc) will be treated as having a trailing slash when matching the prefix (files/etc/).

If no file is found using the above procedure and source is relative, it will search from the location of your Rexfile or the .pm file if you use Perl packages.

All the possible variables ({environment}, {hostname}, ...) are documented in the CMDB YAML documentation.

🫶 Hooks

This function supports the following hooks:

• before — this gets executed before anything is done. All original parameters are passed to it, including the applied defaults (ensure => 'present', resolved path for source). The return value of this hook overwrites the original parameters of the function call. 👀
• before_change — this gets executed right before the new file is written. All original parameters are passed to it, including the applied defaults (ensure => 'present', resolved path for source).
• after_change — this gets executed right after the file is written. All original parameters, including the applied defaults (ensure => 'present', resolved path for source), and any returned results are passed to it.
• after — this gets executed right before the file() function returns. All original parameters, including the applied defaults (ensure => 'present', resolved path for source), and any returned results are passed to it.

💫 get_tmp_file_name($file_name)

To avoid partial changes and to ensure atomic operations when managing files, Rex first creates a temporary file with the new content, then replaces the target file when necessary.

This function returns the name of the temporary file used for a given target file, which may prove useful in hooks. 💅

🦋 file_write($file_name)

This function opens a file for writing (it will truncate the file if it already exists — yes, really, so be careful). It returns a Rex::FS::File object on success.

On failure it will die. 😭

my $fh;
eval {
  $fh = file_write("/etc/groups");
};

# catch an error
if($@) {
  print "An error occurred. $@.\n";
}

# work with the filehandle
$fh->write("...");
$fh->close;

🌈 file_append($file_name)

(yep, it's here, right between the other two — the original page lists it with no extra prose, so no extra prose we shall add 🎀)

⭐ file_read($file_name)

This function opens a file for reading. It returns a Rex::FS::File object on success.

On failure it will die. 😭

my $fh;
eval {
  $fh = file_read("/etc/groups");
};

# catch an error
if($@) {
  print "An error occurred. $@.\n";
}

# work with the filehandle
my $content = $fh->read_all;
$fh->close;

🍓 cat($file_name)

This function returns the complete content of $file_name as a string. so simple, so slay.

print cat "/etc/passwd";

💀 delete_lines_matching($file, $regexp)

Delete lines that match $regexp in $file.

task "clean-logs", sub {
   delete_lines_matching "/var/log/auth.log" => "root";
};

🌸 delete_lines_according_to($search, $file [, @options])

This is the successor of the delete_lines_matching() function. This function also allows the usage of on_change and on_no_change hooks.

It will search for $search in $file and remove the found lines. If on_change hook is present it will execute this if the file was changed.

task "cleanup", "server1", sub {
  delete_lines_according_to qr{^foo:}, "/etc/passwd",
   on_change => sub {
     say "removed user foo.";
   };
};

🧚 append_if_no_such_line($file, $new_line [, @regexp])

Append $new_line to $file if none in @regexp is found. If no regexp is supplied, the line is appended unless there is already an identical line in $file. 👑

---

bestie we are not done, there's more page coming 💖 don't go anywhere —

So like, you already saw append_if_no_such_line doing its thing, but here's the ✨aesthetic✨ version where it also restarts a service when the file actually changes:

task "add-group", sub {
  append_if_no_such_line "/etc/groups", "mygroup:*:100:myuser1,myuser2", on_change => sub { service sshd => "restart"; };
};

And since 0.42 (iykyk) you can use named parameters too, which honestly? slay:

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
};

💡 bestie note: the regexp can be a list of regexps, and that list is an OR. Match any one of them and you're golden.

---

💅 append_or_amend_line($file, $line [, @regexp])

Basically the same energy as append_if_no_such_line, except: if the regexp does find the line, it gets updated instead. If it doesn't find anything? Then it just gets appended like usual. No line left behind, periodt.

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.";
    };
};

---

🦋 extract($file [, %options])

This one extracts a file for you. And the target directory — which you optionally hand over with the to option — gets created automatically. Yes, automatically. Iconic behaviour honestly.

Supported formats are .box, .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .zip, .gz, .bz2, .war, .jar.

task prepare => sub {
  extract "/tmp/myfile.tar.gz",
   owner => "root",
   group => "root",
   to   => "/etc";

  extract "/tmp/foo.tgz",
   type => "tgz",
   mode => "g+rwX";
};

You can also hit it with the type => option if the file suffix has been changed. (the types you can name are tar, tgz, tbz, zip, gz, bz2)

---

🌸 sed($search, $replace, $file [, %options])

Search for some string inside a file and replace it. Very "find and fix my life" of it.

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;
};

And just like all the other similar file management commands, it supports the on_change and on_no_change hooks. Your little callback besties. 🫶

---

🎀 And that's the whole function family, bestie — your files are fed, amended, extracted and sed'd. Go off. 💖

That's a wrap! This page is from the Perl v5.40.1 docs, dated 2025-10-03, and it's the Rex::C...s::File(3pm) manual — source and version and date all tucked in right here at the end, exactly where the footer lives. Mwah. 💅✨