ansible.posix.mount: Mount Filesystems, NFS & CIFS in Ansible (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: installation
Complete guide to ansible.posix.mount module. Mount and unmount NFS, CIFS, ext4, and xfs filesystems with fstab persistence, options, and practical playbook examples.
What Is ansible.posix.mount?
The ansible.posix.mount module manages mount points and /etc/fstab entries on Linux and Unix systems. It can mount and unmount filesystems, add persistent entries to fstab, and handle NFS, CIFS, ext4, xfs, and other filesystem types.
This module replaces the older mount module and is part of the ansible.posix collection.
Installing the ansible.posix Collection
Verify the installation:
Basic Mount Example
Mount an NFS share and add it to fstab:
Module Parameters
| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | path | yes | — | Mount point path on the target host | | src | yes (for mount) | — | Device or remote path (e.g., /dev/sda1, server:/share) | | fstype | yes (for mount) | — | Filesystem type (nfs, cifs, ext4, xfs, tmpfs) | | opts | no | defaults | Mount options (comma-separated) | | state | yes | — | mounted, unmounted, present, absent, remounted | | backup | no | false | Create backup of fstab before modifying | | boot | no | true | Mount at boot (adds to fstab) | | dump | no | 0 | Dump value for fstab entry | | passno | no | 0 | Pass number for fsck | | fstab | no | /etc/fstab | Path to fstab file |
State Options Explained • mounted: Mount the filesystem AND add to fstab. Creates the mount point directory if missing. • unmounted: Unmount the filesystem but keep the fstab entry. • present: Add to fstab without mounting. • absent: Unmount AND remove from fstab. • remounted: Remount an already-mounted filesystem (useful after option changes).
Mount NFS Share
Mount CIFS/SMB Windows Share
Using a credentials file (more secure):
Mount Local Filesystem
Mount tmpfs (RAM Disk)
Unmount and Remove from fstab
Add to fstab Without Mounting
Idempotent Mount with Verification
Common Errors and Solutions
Error: mount point does not exist
The mounted state creates the directory automatically. If using present state, create the directory first:
Error: mount: unknown filesystem type 'nfs'
Install NFS client packages:
Error: mount: permission denied
Ensure become: true is set — mounting requires root privileges.
FAQ
What is the difference between ansible.posix.mount and ansible.builtin.mount?
The ansible.builtin.mount module was deprecated in favor of ansible.posix.mount starting with Ansible 2.11. The posix version is maintained in the ansible.posix collection and receives active updates. Use ansible.posix.mount for all new playbooks.
How do I mount an NFS share persistently with Ansible?
Use state: mounted which both mounts the filesystem immediately and adds the entry to /etc/fstab for persistence across reboots. Combine with opts: defaults,noatime and fstype: nfs or nfs4 for NFS mounts.
Can ansible.posix.mount handle bind mounts?
Yes. Set fstype: none and include bind in the options: opts: bind. This creates a bind mount that maps one directory to another location.
How do I change mount options on an already-mounted filesystem?
Use state: remounted after updating the opts parameter. This unmounts and remounts with the new options without requiring a full unmount/mount cycle.
Related Articles • Mount an NFS share in Linux • Mount a Windows SMB/CIFS share • Ansible for Linux System Administration • Ansible file Module Guide
Category: installation