template($file, @params)¶

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)¶

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

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").

Only called when the "content" parameter is used. For the "source" parameter, the upload hooks are used.

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.

Only called when the "content" parameter is used. For the "source" parameter, the upload hooks are used.

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.

file_write($file_name)¶

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)¶

file_read($file_name)¶

On failure it will die.

 my $fh;
 eval {
   $fh = 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)¶

 print cat "/etc/passwd";

delete_lines_matching($file, $regexp)¶

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

delete_lines_according_to($search, $file, @options)¶

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)¶

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

Since 0.42 you can use named parameters as well

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

append_or_amend_line($file, $line, @regexp)¶

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

extract($file [, %options])¶

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

Can use the type=> option if the file suffix has been changed. (types are tar, tgz, tbz, zip, gz, bz2)

sed($search, $replace, $file)¶

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