ansible.posix.mount Module: Mount NFS, ext4, XFS Filesystems (Complete Guide)

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.

See also: Ansible Mount Module: Mount NFS, CIFS & ansible.posix.mount Guide

Installing the ansible.posix Collection

ansible-galaxy collection install ansible.posix

Verify the installation:

ansible-galaxy collection list | grep ansible.posix

Basic Mount Example

Mount an NFS share and add it to fstab:

---
- name: Mount NFS share
  hosts: all
  become: true
  tasks:
    - name: Mount /data from NFS server
      ansible.posix.mount:
        path: /mnt/data
        src: nfs-server:/exports/data
        fstype: nfs
        opts: defaults,noatime
        state: mounted

See also: Ansible mount Module: Mount Filesystems, NFS, SMB/CIFS Shares (Guide)

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).

See also: Efficient NFS Server Setup with Ansible on Red Hat

Mount NFS Share

- name: Mount NFS v4 share with options
  ansible.posix.mount:
    path: /mnt/nfs-data
    src: 192.168.1.100:/exports/data
    fstype: nfs4
    opts: rw,noatime,hard,intr,rsize=65536,wsize=65536
    state: mounted
    backup: true

Mount CIFS/SMB Windows Share

- name: Mount Windows CIFS share
  ansible.posix.mount:
    path: /mnt/windows-share
    src: //windows-server/shared
    fstype: cifs
    opts: "username=admin,password={{ vault_smb_password }},uid=1000,gid=1000,file_mode=0644,dir_mode=0755"
    state: mounted

Using a credentials file (more secure):

- name: Create CIFS credentials file
  ansible.builtin.copy:
    dest: /root/.smb-credentials
    content: |
      username=admin
      password={{ vault_smb_password }}
      domain=WORKGROUP
    mode: '0600'
- name: Mount CIFS with credentials file
  ansible.posix.mount:
    path: /mnt/windows-share
    src: //windows-server/shared
    fstype: cifs
    opts: "credentials=/root/.smb-credentials,uid=1000,gid=1000"
    state: mounted

Mount Local Filesystem

- name: Mount ext4 partition
  ansible.posix.mount:
    path: /data
    src: /dev/sdb1
    fstype: ext4
    opts: defaults,noatime,nodiratime
    state: mounted
    passno: 2

Mount tmpfs (RAM Disk)

- name: Create tmpfs mount for cache
  ansible.posix.mount:
    path: /tmp/cache
    src: tmpfs
    fstype: tmpfs
    opts: "size=512M,mode=1777"
    state: mounted

Unmount and Remove from fstab

- name: Completely remove mount
  ansible.posix.mount:
    path: /mnt/old-data
    state: absent

Add to fstab Without Mounting

- name: Add fstab entry only (mount at next boot)
  ansible.posix.mount:
    path: /mnt/backup
    src: backup-server:/exports/backup
    fstype: nfs
    opts: defaults,noauto
    state: present

Idempotent Mount with Verification

- name: Mount and verify data volume
  block:
    - name: Mount data volume
      ansible.posix.mount:
        path: /data
        src: /dev/mapper/vg_data-lv_data
        fstype: xfs
        opts: defaults,noatime
        state: mounted
      register: mount_result
- name: Verify mount is accessible
      ansible.builtin.stat:
        path: /data
      register: data_stat
- name: Assert mount is working
      ansible.builtin.assert:
        that:
          - data_stat.stat.exists
          - mount_result is not changed or mount_result is changed
        fail_msg: "Data volume mount failed"

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:

- name: Ensure mount point exists
  ansible.builtin.file:
    path: /mnt/data
    state: directory
    mode: '0755'

Error: mount: unknown filesystem type 'nfs'

Install NFS client packages:

- name: Install NFS utilities
  ansible.builtin.package:
    name: nfs-utils  # nfs-common on Debian/Ubuntu
    state: present

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

See also

• Ansible mount Module: Manage Filesystem Mounts and fstab (Complete Guide)