Documentation

replace - Replace all instances of a particular string in a file using a back-referenced regular expression.

New in version 1.6.

Synopsis

This module will replace all instances of a pattern within a file. It is up to the user to maintain idempotence by ensuring that the same pattern would never match any replacements made.

Options

parameter required default choices comments
backup
no no
  • yes
  • no
Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
dest
yes
    The file to modify.

    aliases: name, destfile
    follow
    (added in 1.9)
    no no
    • yes
    • no
    This flag indicates that filesystem links, if they exist, should be followed.
    group
    no
      name of the group that should own the file/directory, as would be fed to chown
      mode
      no
        mode the file or directory should be. For those used to /usr/bin/chmod remember that modes are actually octal numbers (like 0644). Leaving off the leading zero will likely have unexpected results. As of version 1.8, the mode may be specified as a symbolic mode (for example, u+rwx or u=rw,g=r,o=r).
        others
        no
          All arguments accepted by the file module also work here.
          owner
          no
            name of the user that should own the file/directory, as would be fed to chown
            regexp
            yes
              The regular expression to look for in the contents of the file. Uses Python regular expressions; see http://docs.python.org/2/library/re.html. Uses multiline mode, which means ^ and $ match the beginning and end respectively of each line of the file.
              replace
              no
                The string to replace regexp matches. May contain backreferences that will get expanded with the regexp capture groups if the regexp matches. If not set, matches are removed entirely.
                selevel
                no s0
                  level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the range. _default feature works as for seuser.
                  serole
                  no
                    role part of SELinux file context, _default feature works as for seuser.
                    setype
                    no
                      type part of SELinux file context, _default feature works as for seuser.
                      seuser
                      no
                        user part of SELinux file context. Will default to system policy, if applicable. If set to _default, it will use the user portion of the policy if available
                        validate
                        no None
                          The validation command to run before copying into place. The path to the file to validate is passed in via '%s' which must be present as in the example below. The command is passed securely so shell features like expansion and pipes won't work.

                          Examples

                          - replace: dest=/etc/hosts regexp='(\s+)old\.host\.name(\s+.*)?$' replace='\1new.host.name\2' backup=yes
                          
                          - replace: dest=/home/jdoe/.ssh/known_hosts regexp='^old\.host\.name[^\n]*\n' owner=jdoe group=jdoe mode=644
                          
                          - replace: dest=/etc/apache/ports regexp='^(NameVirtualHost|Listen)\s+80\s*$' replace='\1 127.0.0.1:8080' validate='/usr/sbin/apache2ctl -f %s -t'
                          

                          This is a Core Module

                          For more information on what this means please read Core Modules

                          For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.