Provided by: rex_1.6.0-1_all bug

NAME

       Rex::Commands::File - Transparent File Manipulation

DESCRIPTION

       With this module you can manipulate files.

SYNOPSIS

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

EXPORTED FUNCTIONS

   template($file, @params)
       Parse a template and return the content.

        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.

        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.

       This function supports the following hooks:

       before  This gets executed before everything is done. The return value of this hook
               overwrite the original parameters of the function-call.

       before_change
               This gets executed right before the new file is written. Only with content
               parameter. For the source parameter the hook of the upload function is used.

       after_change
               This gets executed right after the file was written. Only with content parameter.
               For the source parameter the hook of the upload function is used.

       after   This gets executed right before the file() function returns.

   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.

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

        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 an on_change hook.

       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.

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

        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])
       This function extracts a file. The target directory optionally specified with the `to`
       option will be created automatically.

       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)
       Search some string in a file and replace 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;
        };