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

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

The ansible.builtin.mount module control active and configured mount points. This guide covers all common use cases with practical playbook examples.

See also: Ansible file Module: Create Files, Directories, Symlinks (Complete Guide)

Mount a Filesystem

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

NFS Mount

- name: Mount NFS share
  ansible.builtin.mount:
    path: /mnt/shared
    src: "nfs-server.example.com:/exports/shared"
    fstype: nfs
    opts: "rw,sync,hard,intr"
    state: mounted

See also: Ansible find Module: Search Files and Directories (Complete Guide)

tmpfs Mount

- name: Create tmpfs for application cache
  ansible.builtin.mount:
    path: /opt/myapp/cache
    src: tmpfs
    fstype: tmpfs
    opts: "size=512m,mode=1777"
    state: mounted

Add to fstab Without Mounting

- name: Add to fstab (mount on next boot)
  ansible.builtin.mount:
    path: /backup
    src: UUID=abc123-def456
    fstype: ext4
    state: present  # fstab only, don't mount now

See also: Ansible stat Module: Check File Properties and Existence (Complete Guide)

Unmount

- name: Unmount and remove from fstab
  ansible.builtin.mount:
    path: /mnt/old-share
    state: absent  # Unmount and remove fstab entry
- name: Unmount but keep fstab entry
  ansible.builtin.mount:
    path: /mnt/maintenance
    state: unmounted

FAQ

How do I mount a filesystem in Ansible?

Use ansible.builtin.mount with path (mount point), src (device/share), fstype, and state: mounted. This both mounts the filesystem and adds it to /etc/fstab.

What mount states are available?

mounted (mount + fstab), present (fstab only), unmounted (unmount, keep fstab), absent (unmount + remove fstab), remounted (remount with new options).

How do I mount NFS shares with Ansible?

Use mount with fstype: nfs, src: "server:/path", and appropriate opts like rw,sync,hard,intr. Ensure the nfs-common package is installed first.

Conclusion

The ansible.builtin.mount module is a versatile tool for control active and configured mount points. Use the examples above as starting points and adapt them to your infrastructure needs.

Related Articles

• Ansible file Module: Manage Directories • Ansible Playbook Guide

Module Parameters Reference

| Parameter | Required | Default | Description | |---|---|---|---| | path | Yes | — | Mount point path (e.g., /data) | | src | No | — | Device, partition, NFS share, or UUID | | fstype | No | — | Filesystem type (ext4, xfs, nfs, tmpfs, etc.) | | opts | No | defaults | Mount options (comma-separated) | | state | Yes | — | mounted, present, unmounted, absent, remounted | | dump | No | 0 | Dump field in fstab (0 or 1) | | passno | No | 0 | Pass number for fsck in fstab | | fstab | No | /etc/fstab | Path to the fstab file | | backup | No | false | Create backup of fstab before modifying | | boot | No | true | Mount at boot time (sets noauto if false) |

Mount States Explained

┌─────────────┬──────────────┬───────────────┐
│ State       │ Mounts Now?  │ In fstab?     │
├─────────────┼──────────────┼───────────────┤
│ mounted     │ Yes          │ Yes           │
│ present     │ No           │ Yes           │
│ unmounted   │ No (unmount) │ Yes (keep)    │
│ absent      │ No (unmount) │ No (remove)   │
│ remounted   │ Remount      │ No change     │
└─────────────┴──────────────┴───────────────┘

Mount by UUID (Recommended)

Using UUIDs is more reliable than device paths, which can change between reboots:

- name: Get UUID of partition
  ansible.builtin.command: blkid -s UUID -o value /dev/sdb1
  register: disk_uuid
  changed_when: false
- name: Mount data partition by UUID
  ansible.builtin.mount:
    path: /data
    src: "UUID={{ disk_uuid.stdout }}"
    fstype: xfs
    opts: defaults,noatime
    state: mounted
    backup: true

Remount with New Options

- name: Remount /data with new options
  ansible.builtin.mount:
    path: /data
    src: /dev/sdb1
    fstype: ext4
    opts: defaults,noatime,noexec
    state: remounted

CIFS/SMB Mount (Windows Share)

- name: Install CIFS utilities
  ansible.builtin.package:
    name: cifs-utils
    state: present
- name: Mount Windows share
  ansible.builtin.mount:
    path: /mnt/winshare
    src: "//fileserver.example.com/shared"
    fstype: cifs
    opts: "username={{ vault_smb_user }},password={{ vault_smb_pass }},uid=1000,gid=1000,file_mode=0644,dir_mode=0755"
    state: mounted

Bind Mount

- name: Create bind mount
  ansible.builtin.mount:
    path: /var/www/html/uploads
    src: /data/uploads
    fstype: none
    opts: bind
    state: mounted

Complete Playbook: Multi-Disk Server Setup

---
- name: Configure server storage
  hosts: storage_servers
  become: true
vars:
    mounts:
      - path: /data
        src: /dev/sdb1
        fstype: xfs
        opts: defaults,noatime
      - path: /logs
        src: /dev/sdc1
        fstype: ext4
        opts: defaults,noatime,nosuid
      - path: /mnt/nfs-backup
        src: "backup-server.example.com:/exports/backups"
        fstype: nfs
        opts: "rw,sync,hard,intr,timeo=300"
      - path: /tmp/ramdisk
        src: tmpfs
        fstype: tmpfs
        opts: "size=1g,mode=1777"
tasks:
    - name: Ensure NFS client is installed
      ansible.builtin.package:
        name: nfs-utils
        state: present
      when: mounts | selectattr('fstype', 'equalto', 'nfs') | list | length > 0
- name: Create mount point directories
      ansible.builtin.file:
        path: "{{ item.path }}"
        state: directory
        mode: "0755"
      loop: "{{ mounts }}"
- name: Mount all filesystems
      ansible.builtin.mount:
        path: "{{ item.path }}"
        src: "{{ item.src }}"
        fstype: "{{ item.fstype }}"
        opts: "{{ item.opts }}"
        state: mounted
        backup: true
      loop: "{{ mounts }}"
- name: Verify mounts
      ansible.builtin.command: df -h {{ item.path }}
      loop: "{{ mounts }}"
      register: df_output
      changed_when: false
- name: Display mount status
      ansible.builtin.debug:
        msg: "{{ item.stdout }}"
      loop: "{{ df_output.results }}"

What is the difference between mounted and present?

mounted both adds the entry to /etc/fstab and mounts the filesystem immediately. present only adds the fstab entry — the filesystem will be mounted on next boot or manual mount -a.

How do I safely test mount changes?

Use --check mode to preview changes. Also set backup: true to create a backup of /etc/fstab before modifications, allowing easy rollback.

How do I mount a filesystem with credentials?

For CIFS/SMB shares, use a credentials file instead of inline passwords:

- name: Mount with credentials file
  ansible.builtin.mount:
    path: /mnt/share
    src: "//server/share"
    fstype: cifs
    opts: "credentials=/root/.smbcredentials,uid=1000"
    state: mounted