DEBOPS.NFS_SERVER(5)

NAME
debops.nfs_server - manage NFS server using Ansible

SYNOPSIS

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

DESCRIPTION

The debops.nfs_server Ansible role can be used to configure a NFS server on Debian or Ubuntu hosts.

GETTING STARTED

  Default configuration

The role by default focuses on the NFSv4 support. The NFSv3 support can be enabled by setting the nfs_server__v3 variable to True. The Kerberos support is not fully implemented at this point.

By default role expects a list of allowed clients in the nfs_server__allow variable. Example:

nfs_server__allow: [ '192.0.2.0/24' ]

When this list is not empty and contains IP addresses or CIDR subnets, the role will allow access to the nfs service through the firewall and cofigure NFS exports in the /etc/exports.d/ansible.exports configuration file. Only the NFS root pseudo filesystem is defined by default, in the /srv/nfs/ directory. You should define additional exports, for example:

nfs_server__exports:
  - path: '/srv/nfs/shared'
    acl: '192.0.2.0/24'
    options: 'rw,no_subtree_check,no_root_squash'

check the nfs_server__exports documentation for more details.

You can mount the above NFS share on other hosts by using the commands:

mkdir -p /media/nfs/shared
mount -t nfs4 -o proto=tcp,port=2049,_netdev hostname:/shared /media/nfs/shared

You can also add an entry in the /etc/fstab configuration file:

hostname:/shared   /media/nfs/shared   nfs4   noatime,nosuid,hard,intr,proto=tcp,port=2049,_netdev   0   0

Refer to the debops.nfs role for information about how to configure NFS shares on other hosts using Ansible.

  Example inventory

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

[debops_service_nfs_server]
hostname

  Example playbook

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

---
- name: Configure NFS Server
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_nfs_server' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services', 'role::ferm' ]
      etc_services__dependent_list:
        - '{{ nfs_server__etc_services__dependent_list }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ nfs_server__ferm__dependent_rules }}'
    - role: tcpwrappers
      tags: [ 'role::tcpwrappers', 'skip::tcpwrappers' ]
      tcpwrappers__dependent_allow:
        - '{{ nfs_server__tcpwrappers__dependent_allow }}'
    - role: nfs_server
      tags: [ 'role::nfs_server', 'skip::nfs_server' ]

  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::nfs_server
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

DEFAULT VARIABLE DETAILS

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

  nfs_server__exports

This set of YAML lists can be used to define NFS exports. See the exports(5) <https://manpages.debian.org/exports(5)> for more information about possible configuration options.

Each list entry is a YAML dictionary with specific parameters:

path
    Required. Absolute path of the directory which will be exported by NFS. With NFS4, this path should be a subdirectory of the NFS4 root pseudo-filesystem, which by default is defined as /srv/nfs. Refer to the nfs_server__root_path to see the current value.

    The role will create this directory if it doesn't exist. You can use the owner, group and mode parameters to affect the directory ownership and attributes.

options
    A string or a YAML list of the parameters set for a given NFS export. If it's a string, each parameter needs to be delimited by a comma (,) for the role to properly recognize the parameters and convert to a YAML list for internal processing.

bind
    Optional. Absolute path of the directory on the remote host which will be bind-mounted to the specified path. This is useful when you want to export directories that are outside of the NFS4 root pseudo-filesystem.

src A string acting the same way as if you assigned the value directly to the bind option.

options
    A list of extra option to add to the mount. Useful if you need special behavior like waiting for other services to be started before the mount.

acl Required. Access Control List of a given NFS export. This can be either a string (hostname, NIS netgroup, single IP address, single CIDR subnet), or a list of these elements. Alternatively, you can specify a list of YAML dictionaries, each dictionary with specific parameters:

client or clients
    A string or YAML list of valid NFS client definitions.

options
    A string or YAML list of NFS export parameters defined for these clients.

state
    Either present or absent, enables or disables a given client entry.

comment
    Optional. A string or a YAML text block with a comment added to a given NFS export.

state
    Optional. If not specified or present, the NFS export will be present in the configuration file. If absent, the NFS export will not be present in the generated configuration file. This does not have any effect on any bind-mounted directories.

  Examples

Export NFS4 directories from the default /etc/exports configuration file. This is just an example, and the role provides the NFS4 root filesystem automatically, in a different directory.

nfs_server__exports:
  - path: '/srv/nfs4'
    options: 'rw,sync,fsid=0,crossmnt,no_subtree_check'
    acl: 'gss/krb5i'
  - path: '/srv/nfs4/homes'
    options: 'rw,sync,no_subtree_check'
    acl: 'gss/krb5i'

Export the /usr directory read-only, by bind-mounting it to the NFS4 root filesystem. Anyone can access it, barring any firewall configuration:

nfs_server__exports:
  - path: '/srv/nfs/usr'
    bind: '/usr'
    options: [ 'ro', 'no_subtree_check', 'async' ]
    acl: '*'

Export the /srv/media directory for different clients on the two networks, with different set of parameters:

nfs_server__exports:
  - path: '/srv/nfs/media'
    bind: '/srv/media'
    acl:
      - clients: '192.0.2.0/24'
        options: 'ro,no_subtree_check,async'
      - clients: [ '2001:db8:dead:beef::/64', '*.example.org' ]
        options: [ 'rw', 'no_subtree_check', 'no_root_squash' ]

Export the /usr directory read-only, by bind-mounting it to the NFS4 root filesystem, but only after the ZFS service has started. Anyone can access it, barring any firewall configuration:

nfs_server__exports:
  - path: '/srv/nfs/usr'
    bind:
      src: '/usr'
      options:
        - 'x-systemd.requires=zfs-mount.service'
    options: [ 'ro', 'no_subtree_check', 'async' ]
    acl: '*'

AUTHOR
Maciej Delmanowski

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