Documentation

unarchive - Unpacks an archive after (optionally) copying it from the local machine.

New in version 1.4.

Synopsis

The unarchive module unpacks an archive. By default, it will copy the source file from the local system to the target before unpacking - set copy=no to unpack an archive which already exists on the target..

Options

parameter required default choices comments
copy
 no yes
  • yes
  • no
If true, the file is copied from local 'master' to the target machine, otherwise, the plugin will look for src archive at the target machine.
creates
(added in 1.6)
 no
    a filename, when it already exists, this step will not be run.
    dest
    		 yes
      Remote absolute path where the archive should be unpacked
      group
      		 no
        name of the group that should own the file/directory, as would be fed to chown
        list_files
        (added in 2.0)
        		 no no
        • yes
        • no
        If set to True, return the list of files that are contained in the tarball.
        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).
          owner
          		 no
            name of the user that should own the file/directory, as would be fed to chown
            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
                    src
                    		 yes
                      If copy=yes (default), local path to archive file to copy to the target server; can be absolute or relative. If copy=no, path on the target server to existing archive file to unpack.
                      If copy=no and src contains ://, the remote machine will download the file from the url first. (version_added 2.0)

                      Examples

                      # Example from Ansible Playbooks
- unarchive: src=foo.tgz dest=/var/lib/foo

# Unarchive a file that is already on the remote machine
- unarchive: src=/tmp/foo.zip dest=/usr/local/bin copy=no

# Unarchive a file that needs to be downloaded (added in 2.0)
- unarchive: src=https://example.com/example.zip dest=/usr/local/bin copy=no

                      Notes

                      Note

                      requires tar/unzip command on target host

                      Note

                      can handle gzip, bzip2 and xz compressed as well as uncompressed tar files

                      Note

                      detects type of archive automatically

                      Note

                      uses tar’s --diff arg to calculate if changed or not. If this arg is not supported, it will always unpack the archive

                      Note

                      does not detect if a .zip file is different from destination - always unzips

                      Note

                      existing files/directories in the destination which are not in the archive are not touched. This is the same behavior as a normal archive extraction

                      Note

                      existing files/directories in the destination which are not in the archive are ignored for purposes of deciding if the archive should be unpacked or not

                      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.