Using Ansible File Module to Manage Files & Directories

The Ansible file is a module within Ansible that is designed to manage files and directories on remote systems. It changes file properties like ownership, permissions, and timestamps. The module maintains consistency across various servers or systems by guaranteeing that files and folders are in the desired state. 

By handling file-related tasks programmatically, Ansible simplifies system management. The file module enforces the correct state during automation runs.

The file module supports various operations, such as creating, deleting, and modifying files or directories, and checking for file existence. This makes it an integral part of any automation strategy, especially when combined with other Ansible modules to perform comprehensive system configurations.

While the Ansible file module is ideal for managing files and directories, you can combine it with modules like cron to schedule automated tasks that rely on the presence of specific files or directories, enabling more robust system automation.

The basic structure of the Ansible file module

When using the Ansible file module, you should be aware of several key parameters:

• path : Specifies the file or directory path to manage
• state: Defines the state of the file. Common values include:
  • file (ensures the path is a file)
  • directory (ensures the path is a directory)
  • absent (removes the file or directory if it exists)
• owner: Defines the user that should own the file or directory
• group: Specifies the group that should own the file or directory
• mode: Specifies the permissions for the file or directory, expressed in octal format (e.g., 0755)
• recurse: When managing directories, this parameter recursively applies the specified ownership and permissions to all files and subdirectories

The example below is a playbook that ensures a specific directory exists with the correct ownership and permissions:

The above task ensures that the /var/log/myapp directory is present, owned by root, and has the permission mode 0755.

If the directory does not exist, Ansible creates it. However, if it exists but with different permissions or ownership, Ansible updates it to match the specified state.

Key features of the Ansible file module

The following are some key features of the Ansible file module:

• File creation and removal: Administrators can use the Ansible file module to create or remove files and directories on remote systems. It takes the manual work out of routine tasks, ensuring everything is in place or cleared out, based on what the setup needs.
• Permissions and ownership control: The module provides functionality to modify file permissions (e.g., read, write, execute) and ownership (i.e., user and group), ensuring files are accessible only by the intended users.
• File timestamp management: It allows for timestamp updates (modifying access and modification times) on files. This can be useful when managing cron jobs or log files. 
• Idempotency: The module is idempotent, meaning it will not perform an action if the file’s state already matches the desired configuration. This ensures efficiency in automation, preventing unnecessary changes.

For more context on setting up directory structures with Ansible, see this blog post on creating directories with Ansible.

Use cases

The Ansible file module is versatile and can be applied in various scenarios:

1. System setup and configuration: During the setup of a new system, administrators can use this module to ensure that necessary files and directories are created, along with the correct permissions and ownership, reducing manual intervention.
2. Securing files: Maintaining security standards requires ensuring files have the correct permissions. The Ansible file module helps enforce security policies by setting strict file permissions and ownership. This can safeguard sensitive data and prevent unauthorized access.
3. Log management: Managing log files on servers often involves monitoring who owns them, their permissions, and when they were last touched. The file module in Ansible can automate this routine and ensure that logs are managed the same way every time.
4. Maintenance tasks: Old or unused files build up as systems run over time. The file module in Ansible helps clean things up by removing what’s no longer needed, keeping your systems tidy and easier to manage.

In this section, we’ll show how to use the file module to perform everyday tasks, such as ensuring the right folders are in place, permissions are set correctly, and old files are cleaned up.

Creating files on remote hosts

To create a file on a remote host with the Ansible file module, set the state parameter to touch, and specify the desired path. Here’s an example:

This task creates a file at the specified location with the defined permissions. If the file already exists, its timestamp will be updated to the current time.

The following output will be generated when the playbook is executed:

Checking if the file exists

The file module can also be used to check whether a file exists. For instance, using the state parameter in conjunction with the file module can help determine the existence of a file before proceeding with further actions.

The following output will be generated when the playbook is executed:

Updating file timestamps

If you only want to update the timestamps of a file without modifying its content or permissions, you can use the state: touch option. Here’s how:

The following output will be generated when the playbook is executed:

Managing file permissions and ownership

To modify the ownership and permissions of a file, you can use the owner, group, and mode parameters in the Ansible file module. For example:

This task changes the file’s ownership to the user and group while setting the file permissions to 0755. It allows read and execute permissions for everyone and write permission only for the owner.

The following output will be generated when the playbook is executed:

Deleting files on remote hosts

To delete a file with the Ansible file module, you can set the state parameter to absent. Here’s an example:

This will remove the file if it exists on the remote host.

The following output will be generated when the playbook is executed:

Creating directories

To create a directory with the Ansible file module, specify the state parameter as directory:

This ensures that the directory is created with the correct permissions.

The following output will be generated when the playbook is executed:

Checking if the directory exists

Similarly, you can check if a directory exists using the file module with state: directory. If the directory already exists, the task will ensure it remains desired.

The following output will be generated when the playbook is executed:

Creating an empty file

You can create an empty file using Ansible’s file module by setting state: touch. This ensures the file exists, creating it if necessary, and updating its timestamp if it already exists.

For example:

This will create /tmp/example.txt if it doesn’t already exist, without adding any content.

Let’s put all of this together in a practical example. 

This playbook sets up a consistent logging structure across all your systems. It handles directory creation, adds the log file if needed, and sets the right ownership and permissions.

Here’s how you can use the Ansible file module to achieve that:

This example ensures that a directory and log file are created and proper ownership and permissions are applied.

What does this playbook do?

The play is applied to all remote hosts listed in your Ansible inventory. If needed, you can replace all of them with a specific host group, such as webservers or backend-nodes.

The playbook uses the Ansible file module to ensure the /var/log/myapp directory exists on all targeted systems. By setting state: directory and mode: '0755', it provides the directory with read, write, and execute permissions for the owner and read-execute access for other users.

This task uses state: touch to create a file named app.log inside the /var/log/myapp directory if it doesn’t already exist. If it exists, the module updates its last modified timestamp.

This final task updates the log file’s ownership to a specific application user and group (e.g., user:group). It also modifies its permissions to 0755. 

The following output will be generated when the playbook is executed:

The copy module transfers files from the local control node to a remote host, making it useful for distributing static files. The file module, on the other hand, manages file properties like ownership, permissions, or symlink state without transferring content.

Here are the key differences between the Ansible file and copy modules:

Spacelift’s vibrant ecosystem and excellent GitOps flow are helpful for managing and orchestrating Ansible. By introducing Spacelift on top of Ansible, you can easily create custom workflows based on pull requests and apply any necessary compliance checks for your organization.

Another advantage of using Spacelift is that you can manage infrastructure tools like Ansible, Terraform, Pulumi, AWS CloudFormation, and even Kubernetes from the same place and combine their stacks with building workflows across tools.

Our latest Ansible enhancements solve three of the biggest challenges engineers face when they are using Ansible:

• Having a centralized place in which you can run your playbooks
• Combining IaC with configuration management to create a single workflow
• Getting insights into what ran and where

Provisioning, configuring, governing, and even orchestrating your containers can be performed with a single workflow, separating the elements into smaller chunks to identify issues more easily.

Would you like to see this in action, or just get a tl;dr? Check out this video showing you Spacelift’s Ansible functionality:

If you want to learn more about using Spacelift with Ansible, check our documentation, read our Ansible guide, or book a demo with one of our engineers.

This article explored the Ansible file module and how it helps simplify file and directory management across systems. Unlike the copy module, which focuses on transferring file contents, the file module manages file attributes from permissions to ownership without touching the content inside.

We also explored how the file module makes managing files and directories on remote systems easier, helping maintain structure and consistency.

We discussed practical examples, such as setting permissions, cleaning up old files, and using the module as part of a larger automation workflow.

So, whether you’re ensuring compliance or keeping your infrastructure in check, a few well-placed parameters with the file module can do the job.