DEBOPS.MOUNT(5)

NAME
debops.mount - Manage local device and bind mounts using Ansible

SYNOPSIS

debops run service/mount [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.mount Ansible role can be used to manage local filesystem mounts as well as bind mounts in the /etc/fstab database. Custom directories can also be created by this role, with support for normal as well as ACL attributes.

This role is meant to be used to configure local filesystems, for remote filesystems, you can use the debops.nfs role instead, which will configure the NFS client service.

GETTING STARTED

  Example inventory

The debops.mount role is included by default in the DebOps common.yml playbook and does not need to be explicitly enabled. It can be disabled if needed, by setting the mount__enabled boolean variable to False in the Ansible inventory.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.mount role:

---
- name: Manage local device and bind mounts
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_mount' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: mount
      tags: [ 'role::mount', 'skip::mount' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::mount
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.mount Ansible role:

•   Manual pages: fstab(5) <https://manpages.debian.org/fstab(5)>, systemd.mount(5) <https://manpages.debian.org/systemd.mount(5)>, systemd.automount(5) <https://manpages.debian.org/systemd.automount(5)>

•   Ansible ansible.posix.mount module <https://docs.ansible.com/ansible/latest/collections/ansible/posix/mount_module.html> documentation

•   Debian Wiki: fstab <https://wiki.debian.org/fstab>

•   Arch Linux Wiki: fstab <https://wiki.archlinux.org/index.php/Fstab>

•   StackExchange: What is a bind mount? <https://unix.stackexchange.com/a/198591>

DEFAULT VARIABLE DETAILS

Some of debops.mount default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  mount__devices

The mount__*_devices variables define a list of YAML dictionaries that configure local device mounts. They can be used to configure any mount type, however remote devices should be avoided (the role is executed early in the DebOps common.yml playbook, when network configuration might not be finished), and bind mounts have their own set of variables and a separate task to allow creation of source directories.

The role does not create new filesystems, the devices configured by it should have their own filesystems configured and formatted beforehand.

  Examples

Create an /etc/fstab entry for a disk drive that's not mounted on boot, with specific filesystem type:

mount__devices:
  - name: '/media/backups'
    src: '/dev/sdb1'
    fstype: 'ext4'
    opts: 'defaults,noauto,nofail'

Create an automount entry for an USB drive using systemd automount functionality (you can find its UUID with lsblk -f command):

mount__devices:
  - name: '/media/USB_Stick'
    src: 'UUID=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
    opts: [ 'defaults', 'noauto', 'nofail', 'x-systemd.automount',
            'x-systemd.idle-timeout=2', 'x-systemd.device-timeout=2',
            'x-systemd.mount-timeout=2' ]
    # Without this, Ansible tries to mount the drive right away which
    # results in an error
    state: 'present'

  Syntax

Each mount__*_devices list entry is a YAML dictionary with specific parameters. Most of the parameters are the same as the Ansible mount module:

src Required. A device name which will be mounted at a given path. It can be a block device file in /dev directory, or a label, or device UUID. See fstab(5) <https://manpages.debian.org/fstab(5)> manual page, first field description for more details.

path / dest / name
    Required. Absolute path in the filesystem where a given device will be mounted.

fstype
    Optional. Specify the filesystem type to use with a given device. If not specified, auto will be used to perform autodetection.

opts
    Optional. String (comma-delimited) or YAML list of options for a given mount point. If not specified, defaults will be used instead.

dump
    Optional. This field determines which filesystems should be backed up by the dump(8) <https://manpages.debian.org/dump(8)> command. If not specified, 0 is set by default.

passno
    Optional. This field determines the order of the filesystem checks on boot done by the fsck(8) <https://manpages.debian.org/fsck(8)> command. The root filesystem should be it set to 1, other filesystems should be set to 2. If not specified, it defaults to 0, which disables filesystem checks on boot.

state
    Optional. If not specified or mounted, the device entry will be added to the /etc/fstab database and it will be automatically mounted. Unmounted devices will be mounted again. If the mount point directory is not present, it will be automatically created.

    If present, the device entry will be added to /etc/fstab, but Ansible will not try to mount it right away (preferable for automounted devices). Already mounted devices will not be changed.

    If unmounted, Ansible will try and unmount the already mounted device. The /etc/fstab database will not be changed, however missing entries will be added.

    If absent, the mounted device will be unmounted, and the /etc/fstab database entry, along with the mount point directory, will be removed.

fstab
    Optional. Absolute path of the alternative fstab(5) <https://manpages.debian.org/fstab(5)> database to use instead of the default /etc/fstab database.

    Additional parameters control functions outside of the Ansible mount module:

device
    Optional. The role creates the required mount points by itself instead of letting the Ansible mount module do it; this allows for fine-grained control over initial mount point attributes. The task that creates the mount points is not executed when they are actually mounted - the role checks if the src parameter is present in the ansible_mounts fact entries as the device dictionary key.

    In case that the src parameter and the expected device dictionary key are different, you can set the device parameter to override the check.

owner
    Optional. Specify the UNIX account that will be the owner of the initial mount point, before the device is mounted. If not specified, root will be the owner.

group
    Optional. Specify the UNIX group that will be the group of the initial mount point, before the device is mounted. If not specified, the value of owner is used, otherwise root will be the group.

mode
    Optional. Specify the UNIX permissions that will be applied to the initial mount point, before the device is mounted. If not specified, 0755 will be set by default.

  mount__directories

The mount__*_directories variables are list of YAML dictionaries, each entry defining a directory in the filesystem, with optional attributes. These variables can be used to create, modify or remove directories in the filesystems after they are mounted.

  Examples

Create a directory owned by root on the mounted filesystem:

mount__directories:
  - path: '/media/USB_Stick/Private'

Create directory for data sharing between unprivileged LXC containers. This assumes that the unprivileged LXC containers are started by root and use subUID/subGID range defined by the debops.root_account Ansible role:

mount__directories:
  - path: '/srv/shared/lxc-opt'
    owner: '100000'
    group: '100000'
    mode: '0751'

Create directory with custom ACL permissions that allows the www-data UNIX group to write files:

mount__directories:
  - path: '/srv/www'
  - path: '/srv/www/data'
    owner: 'root'
    group: 'root'
    mode: '0750'
    acl:
      - entity: 'www-data'
        etype: 'group'
        permissions: 'rwx'

  Syntax

The mount__*_directories lists contain YAML dictionaries, each dictionary can have specific parameters, that reflect the Ansible file module parameters:

path / dest / name
    Required. Absolute path of the directory that is managed by the role.

owner
    Optional. Specify the UNIX account that should be the owner of the directory. If not specified, root is used by default.

group
    Optional. Specify the UNIX group that should be the main group of the given directory. If not specified, the value of owner is used by default, otherwise root is set.

mode
    Optional. Set the permissions of the managed directory. If not specified, 0755 will be used by default.

recurse
    Optional, boolean. If defined and True, the role will set the specified permissions and ownership recursively to all subdirectories of the given directory as well as to the directory itself.

state
    Optional. If not specified or directory, the given directory will be created or updated with the specified permissions and ownership. If absent, the given directory will be removed. Other values of the state parameter are ignored in this role.

acl Optional. This parameter defines Access Control List entries for a given directory, each entry is a YAML dictionary with specific parameters:

entity
    Name of the ACL entity to manage, either UNIX account or UNIX group.

etype
    The entity type of a given ACL, check the setfacl(1) <https://manpages.debian.org/setfacl(1)> manual page for more details. Choices: user, group, other, mask.

permissions
    Specify the permissions to set for a given ACL entry, they can be a combination of r (read), w (write) and x (execute).

default
    Optional, boolean. If defined and True, a given ACL entry will be the default for all entities created inside of a given directory.

follow
    Optional, boolean. If set and True, the Ansible module will follow the symlinked directory to the symlink target and change its attributes instead of the symlink attributes.

recursive
    Optional, boolean. If set and True, the Ansible module will apply the specified ACL to all objects in a given path.

state
    Optional. If not set or present, the ACL entry will be added to the current object. If absent, the ACL entry will be removed from the current path.

  mount__binds

The mount__*_binds variables can be used to create bind mounted directories in the filesystem. Bind mounts are similar to symlinks, where a given directory is mounted at a different place in the filesystem. This can be used to give access to parts of the filesystem in a different namespace, for example in a LXC container.

The task that manages the bind mounts are separate from the "normal" mounts to allow the system to mount devices that could have parts of their filesystem bind-mounted later on.

  Examples

Bind mount the USB drive at a different point in the filesystem:

mount__binds:
  - src: '/media/USB_Stick'
    dest: '/srv/removable/data'

  Syntax

Each mount__*_binds list entry is a YAML dictionary with specific parameters. The parameters are the same as the Ansible mount module:

src Required. A directory name which will be bind mounted at a given path. The directory should already exist. You can use the mount__directories variables to create the directories beforehand.

path / dest / name
    Required. Absolute path in the filesystem where a given directory will be bind mounted.

fstype
    Optional. Specify the filesystem type to use with a given device. If not specified, none will be used, which is required for bind mounts.

opts
    Optional. String (comma-delimited) or YAML list of options for a given mount point. If not specified, bind will be used instead.

dump
    Optional. This field determines which filesystems should be backeed up by the dump(8) <https://manpages.debian.org/dump(8)> command. If not specified, 0 is set by default.

passno
    Optional. This field determines the order of the filesystem checks on boot done by the fsck(8) <https://manpages.debian.org/fsck(8)> command. The root filesystem should be it set to 1, other filesystems should be set to 2. If not specified, it defaults to 0, which disables filesystem checks on boot.

state
    Optional. If not specified or mounted, the bind mount entry will be added to the /etc/fstab database and it will be automatically mounted. Unmounted bind directories will be mounted again. If the mount point directory is not present, it will be automatically created.

    If present, the bind mount entry will be added to /etc/fstab, but Ansible will not try to mount it right away (preferable for automounted devices). Already mounted bind directories will not be changed.

    If unmounted, Ansible will try and unmount the already bind mounted directories. The /etc/fstab database will not be changed, however missing entries will be added.

    If absent, the bind mounted directory will be unmounted, and the /etc/fstab database entry, along with the mount point directory, will be removed.

fstab
    Optional. Absolute path of the alternative fstab(5) <https://manpages.debian.org/fstab(5)> database to use instead of the default /etc/fstab database.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others