Updated April 6, 2023
Introduction to Ansible untar
Ansible untar module also known as unarchive for Unix OS or win_zip for the windows operating system is used to extract or unpack the archive files or folders on the remote destination by copying the archive file first by default on the remote server and also supports many parameters to deal with the unarchive or win_zip functionality like the owner, dest, exclude and more.
Syntax
For the non-windows target unarchive or ansible.builtin.unarchive command uses the below syntax. We have shown the basics parameters
- Parameters:
- copy: No / Yes (Default)
- The default Option is Yes and it copies the files from the local controller to the remote host if specified yes or nothing specified. For working with the remote source need to specify the remote_src and this copy parameter is not helpful there.
- src (required):
- Source path of the file. If remote_src is ‘yes’ then the source path would be on the remote location otherwise the source path is on the local controller node.
- dest (required):
- Remote server absolute path where the archive is going to extract.
- remote_src: no (Default) / yes
- If set ‘yes’ specifies that the source archive path is on the remote computer. For the ‘no’ value the path is on the local controller node.
- owner:
- name of the user that should own the files/directory after unpack and same replicates (added) to the chown.
- group:
- Name of the group that should own the files/directory and same replicates (added) to the chown.
- exclude:
- List of files or directories that need to be excluded from the unpacking.
- include:
- List of files or directories that need to be included in the unpacking process.
- keep_newer: no (default) / yes
- If set yes, it replaces the existing files that are newer than the files inside the archive.
- mode:
- Permissions that the files or directories should have after unpacked (like 644, 777, etc).
- copy: No / Yes (Default)
There are other additional parameters like creates, seuser, serole, setype, selevel, unsafe_writes, validate_certs.
For the windows target src, dest, creates parameters remain the same as unarchive module and the additional parameters are as below.
- Parameters:
- delete_archive: no (default) / yes
- Removes the zip file after unzipping.
- password
- If the Zip file is password encrypted then this parameter is useful and it requires the PSCX module to be installed.
- recurse: no (default) / yes
- recursively expands the zip file within the src directory.
- Setting value ‘yes’ requires the PSCX module to be installed.
- delete_archive: no (default) / yes
Please note: the win_unzip module doesn’t use the remote_src parameter.
How untar works in Ansible?
Ansible unarchive module for non-windows target comes with the ansible-base and so it is included in the Ansible installations. For the windows target, we need to use the win_unzip module. If the module is not available then you can download it from the galaxy.
ansible-galaxy collection install community.windows
Below is the simple playbook for windows untar (unzip).
---
- name: Ansible playbook for windows unzip module
hosts: winservers
tasks:
- name: Unzip the file from the remote location
win_unzip:
src: \\ad\shared\7zipModule.zip
dest: c:\temp\7zipInstaller
Output:
The above playbook will unzip the file from the source location to the destination remote servers. If the destination path doesn’t exist it creates the destination path.
You must have noticed here, although the source path is remote, we don’t need to use remote_src because the win_unzip module doesn’t support it and when we use the remote source path for the non-target windows server we must specify the remote_src. For example,
tasks:
- name: unarchive for from the remote source on the non-windows target
win_unzip:
src: /tmp/myfiles/7zipmodule.tar.gz
dest: /tmp/7zipmodule
remote_src: yes
Examples
Here are the following examples mention below
Example #1 – unarchive module task for UNIX os.
Code:
---
- name: Ansible playbook to unarchive the files on the remote nodes.
hosts: linuxservers
tasks:
- name: Extract the archive file on the remote node
unarchive:
src: /etc/installers/phayes-geoPHP-1.2-20-g6855624.tar.gz
dest: /tmp/phyes
In this playbook, it will retrieve the .tar.gz file to the destination remote host /tmp/phyes. Before running this task unlike the win_unzip module, you need to make sure that the destination path exists otherwise it will throw an error.
Output:
Example #2 – Exclude files from the archive.
To exclude the certain file from the unpacking we can use h
Code:
---
- name: Ansible playbook to unarchive the files on the remote nodes.
hosts: linuxservers
tasks:
- name: Extract the archive file with exluding text document
unarchive:
src: /etc/installers/phayes-geoPHP-1.2-20-g6855624.tar
dest: /tmp/phyes
exclude: 'Test1 document.txt'
If there are multiple files to exclude then you can provide the list as below.
unarchive:
src: /etc/installers/phayes-geoPHP-1.2-20-g6855624.tar
dest: /tmp/phyes
exclude:
- 'Test1 document.txt'
- 'Test2 document.txt'
- 'sourcefile.py'
Example #3 – Include files from the archive
Please note: To use the include parameter, we need ansible.builtin version 2.11.
Code:
tasks:
- name: Extract the archive file with including text document
unarchive:
src: /etc/installers/phayes-geoPHP-1.2-20-g6855624.tar
dest: /tmp/phyes
include: 'Test1 document.txt'
The above playbook will include only the test1 text file and to include the multiple documents, use the below command.
unarchive:
src: /etc/installers/phayes-geoPHP-1.2-20-g6855624.tar
dest: /tmp/phyes
include:
- 'Test1 document.txt'
- 'Test2 document.txt'
- 'sourcefile.py'
Example #4 – using multiple parameters together.
Code:
---
- name: Ansible playbook to unarchive the files on the remote nodes.
hosts: linuxservers
tasks:
- name: Extract the archive file with including text document
unarchive:
src: /etc/installers/phayes-geoPHP-1.2-20-g6855624.tar
dest: /tmp/phyes
include:
- 'Test1 document.txt'
- 'Test2 document.txt'
keep_newer: no
mode: 0644
remote_src: yes
owner: ansibleadmin
In the above playbook, it will include only 2 files, keep_newer parameter will not replace the existing files that are newer than files from the archive, remote_src indicates the remote source and it will set the owner permission on the files and it will keep the file permission 0644.
Conclusion
Untar or unarchive or unzip modules are very useful when we write the playbook. It makes it easier to extract the files or folders on the destination server without using any third-party software and in addition, it uses various parameters like we don’t need to copy the file before extracting, adding permissions after extract, etc.
Recommended Articles
This is a guide to Ansible untar. Here we discuss How untar works in Ansible and Examples along with the codes and outputs. You may also look at the following articles to learn more –
