DEBOPS.NFS(5)

NAME
debops.nfs - manage NFS4 client using Ansible

SYNOPSIS

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

DESCRIPTION

The debops.nfs Ansible role can be used to configure NFS shares on Debian/Ubuntu hosts.

GETTING STARTED

  Default configuration

The role does not specify any NFS shares by default, you need to configure them using the provided variables (see nfs__shares for more details).

The configured NFS shares should exist and be available prior to the role execution, otherwise Ansible will hang waiting for the finished mount command. You can use the debops.nfs_server role to configure NFS4 shares.

  Example inventory

To enable NFS support on a host it needs to be included in the specific Ansible inventory group:

[debops_service_nfs]
hostname

  Example playbook

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

---
- name: Manage NFS shares
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_nfs' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: nfs
      tags: [ 'role::nfs', 'skip::nfs' ]

DEFAULT VARIABLE DETAILS

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

  nfs__shares

The nfs__shares, nfs__group_shares and nfs__host_shares are list of NFS shares to configure on a host. Each list element is a YAML dictionary with specific parameters:

path
    Required. Absolute path of a directory where the given NFS share should be mounted. If the directory does not exist, it will be created by the role.

src Required. Mount point "source", usually in the form of:

    <hostname>:/<share_path>

    You can use either DNS names or IP addresses.

    NOTE: If you want to use NFSv4 mount points, you need to specify share paths relative to the NFS root directory configured on the nfs server.

state
    Optional. If not specified or mounted, the given NFS share will be added to the /etc/fstab configuration file and automatically mounted. If present, the NFS mount will be added to the /etc/fstab but its state will not be changed. If unmounted, and the NFS share is mounted, it will be unmounted. If absent, the NFS share will be unmounted and its entry will be removed from /etc/fstab configuration file.

options or opts
    Optional. A comma-separated string or a YAML list of mount options which should be used with a given NFS share. If not specified, the role will use a set of default options that configure the mount to be a network NFS4 share.

default_options
    Optional, boolean. If present and False, the role will not add the default options to the custom ones provided by the user, which will allow full control over the configuration. The _netdev option is always added to ensure that the /etc/fstab configuration file remains valid.

fstype
    Optional. Specify the filesystem type to use for the mount point. By default it's nfs4.

passno, dump, fstab
    Optional. Additional parameters passed to the Ansible mount module, by default omitted since they are not useful for NFS shares. See the module documentation page for more details.

owner, group, mode
    Optional. Specify UNIX account, group and directory permissions for the mount point of a given NFS share. They will be applied to the directories created by the role when the NFS share is not mounted immediately.

  Examples

Mount a NFS4 share with automatic configuration:

nfs__shares:
  - path: '/media/nfs/shared'
    src: 'nas.example.org:/shared'

Create an automount entry for a NFSv4 share using systemd automount functionality:

nfs__shares:
  - path: '/media/nfs/shared'
    src: 'nas.example.org:/shared'
    opts: [ 'defaults',  '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 share right away which
    # results in an error
    state: 'present'

AUTHOR
Maciej Delmanowski

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