.. _nfs_module:


nfs -- Manage NFS export on Unity storage system
================================================

.. contents::
   :local:
   :depth: 1


Synopsis
--------

Managing NFS export on Unity storage system includes- Create new NFS export, Modify NFS export attributes, Display NFS export details, Delete NFS export.



Requirements
------------
The below requirements are needed on the host that executes this module.

- A Dell Unity Storage device version 5.1 or later.
- Ansible-core 2.17 or later.
- Python 3.11, or 3.12.
- Storops Python SDK 1.2.12.



Parameters
----------

  nfs_export_name (optional, str, None)
    Name of the nfs export.

    Mandatory for create operation.

    Specify either *nfs_export_name* or *nfs_export_id* (but not both) for any operation.


  nfs_export_id (optional, str, None)
    ID of the nfs export.

    This is a unique ID generated by Unity storage system.


  filesystem_name (optional, str, None)
    Name of the filesystem for which NFS export will be created.

    Either filesystem or snapshot is required for creation of the NFS.

    If *filesystem_name* is specified, then *nas_server* is required to uniquely identify the filesystem.

    If filesystem parameter is provided, then snapshot cannot be specified.


  filesystem_id (optional, str, None)
    ID of the filesystem.

    This is a unique ID generated by Unity storage system.


  snapshot_name (optional, str, None)
    Name of the snapshot for which NFS export will be created.

    Either filesystem or snapshot is required for creation of the NFS export.

    If snapshot parameter is provided, then filesystem cannot be specified.


  snapshot_id (optional, str, None)
    ID of the snapshot.

    This is a unique ID generated by Unity storage system.


  nas_server_name (optional, str, None)
    Name of the NAS server on which filesystem will be hosted.


  nas_server_id (optional, str, None)
    ID of the NAS server on which filesystem will be hosted.


  path (optional, str, None)
    Local path to export relative to the NAS server root.

    With NFS, each export of a file_system or file_snap must have a unique local path.

    Mandatory while creating NFS export.


  description (optional, str, None)
    Description of the NFS export.

    Optional parameter when creating a NFS export.

    To modify description, pass the new value in *description* field.

    To remove description, pass the empty value in *description* field.


  host_state (optional, str, None)
    Define whether the hosts can access the NFS export.

    Required when adding or removing access of hosts from the export.


  anonymous_uid (optional, int, None)
    Specifies the user ID of the anonymous account.

    If not specified at the time of creation, it will be set to 4294967294.


  anonymous_gid (optional, int, None)
    Specifies the group ID of the anonymous account.

    If not specified at the time of creation, it will be set to 4294967294.


  state (True, str, None)
    State variable to determine whether NFS export will exist or not.


  default_access (optional, str, None)
    Default access level for all hosts that can access the NFS export.

    For hosts that need different access than the default, they can be configured by adding to the list.

    If *default_access* is not mentioned during creation, then NFS export will be created with ``NO_ACCESS``.


  min_security (optional, str, None)
    NFS enforced security type for users accessing a NFS export.

    If not specified at the time of creation, it will be set to ``SYS``.


  adv_host_mgmt_enabled (optional, bool, None)
    If ``false``, allows you to specify hosts without first having to register them.

    Mandatory while adding access hosts.


  no_access_hosts (optional, list, None)
    Hosts with no access to the NFS export.

    List of dictionaries. Each dictionary will have any of the keys from *host_name*, *host_id*, *subnet*, *netgroup*, *domain* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``true`` then the accepted keys are *host_name*, *host_id* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``false`` then the accepted keys are *host_name*, *subnet*, *netgroup*, *domain* and *ip_address*.


    host_name (optional, str, None)
      Name of the host.


    host_id (optional, str, None)
      ID of the host.


    ip_address (optional, str, None)
      IP address of the host.


    subnet (optional, str, None)
      Subnet can be an 'IP address/netmask' or 'IP address/prefix length'.


    netgroup (optional, str, None)
      Netgroup that is defined in NIS or the local netgroup file.


    domain (optional, str, None)
      DNS domain, where all NFS clients in the domain are included in the host list.



  read_only_hosts (optional, list, None)
    Hosts with read-only access to the NFS export.

    List of dictionaries. Each dictionary will have any of the keys from *host_name*, *host_id*, *subnet*, *netgroup*, *domain* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``true`` then the accepted keys are *host_name*, *host_id* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``false`` then the accepted keys are *host_name*, *subnet*, *netgroup*, *domain* and *ip_address*.


    host_name (optional, str, None)
      Name of the host.


    host_id (optional, str, None)
      ID of the host.


    ip_address (optional, str, None)
      IP address of the host.


    subnet (optional, str, None)
      Subnet can be an 'IP address/netmask' or 'IP address/prefix length'.


    netgroup (optional, str, None)
      Netgroup that is defined in NIS or the local netgroup file.


    domain (optional, str, None)
      DNS domain, where all NFS clients in the domain are included in the host list.



  read_only_root_hosts (optional, list, None)
    Hosts with read-only for root user access to the NFS export.

    List of dictionaries. Each dictionary will have any of the keys from *host_name*, *host_id*, *subnet*, *netgroup*, *domain* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``true`` then the accepted keys are *host_name*, *host_id* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``false`` then the accepted keys are *host_name*, *subnet*, *netgroup*, *domain* and *ip_address*.


    host_name (optional, str, None)
      Name of the host.


    host_id (optional, str, None)
      ID of the host.


    ip_address (optional, str, None)
      IP address of the host.


    subnet (optional, str, None)
      Subnet can be an 'IP address/netmask' or 'IP address/prefix length'.


    netgroup (optional, str, None)
      Netgroup that is defined in NIS or the local netgroup file.


    domain (optional, str, None)
      DNS domain, where all NFS clients in the domain are included in the host list.



  read_write_hosts (optional, list, None)
    Hosts with read and write access to the NFS export.

    List of dictionaries. Each dictionary will have any of the keys from *host_name*, *host_id*, *subnet*, *netgroup*, *domain* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``true`` then the accepted keys are *host_name*, *host_id* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``false`` then the accepted keys are *host_name*, *subnet*, *netgroup*, *domain* and *ip_address*.


    host_name (optional, str, None)
      Name of the host.


    host_id (optional, str, None)
      ID of the host.


    ip_address (optional, str, None)
      IP address of the host.


    subnet (optional, str, None)
      Subnet can be an 'IP address/netmask' or 'IP address/prefix length'.


    netgroup (optional, str, None)
      Netgroup that is defined in NIS or the local netgroup file.


    domain (optional, str, None)
      DNS domain, where all NFS clients in the domain are included in the host list.



  read_write_root_hosts (optional, list, None)
    Hosts with read and write for root user access to the NFS export.

    List of dictionaries. Each dictionary will have any of the keys from *host_name*, *host_id*, *subnet*, *netgroup*, *domain* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``true`` then the accepted keys are *host_name*, *host_id* and *ip_address*.

    If *adv_host_mgmt_enabled* is ``false`` then the accepted keys are *host_name*, *subnet*, *netgroup*, *domain* and *ip_address*.


    host_name (optional, str, None)
      Name of the host.


    host_id (optional, str, None)
      ID of the host.


    ip_address (optional, str, None)
      IP address of the host.


    subnet (optional, str, None)
      Subnet can be an 'IP address/netmask' or 'IP address/prefix length'.


    netgroup (optional, str, None)
      Netgroup that is defined in NIS or the local netgroup file.


    domain (optional, str, None)
      DNS domain, where all NFS clients in the domain are included in the host list.



  unispherehost (True, str, None)
    IP or FQDN of the Unity management server.


  username (True, str, None)
    The username of the Unity management server.


  password (True, str, None)
    The password of the Unity management server.


  validate_certs (optional, bool, True)
    Boolean variable to specify whether or not to validate SSL certificate.

    ``true`` - Indicates that the SSL certificate should be verified.

    ``false`` - Indicates that the SSL certificate should not be verified.


  port (optional, int, 443)
    Port number through which communication happens with Unity management server.





Notes
-----

.. note::
   - The *check_mode* is not supported.
   - The modules present in this collection named as 'dellemc.unity' are built to support the Dell Unity storage platform.




Examples
--------

.. code-block:: yaml+jinja

    
    - name: Create nfs export from filesystem
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_name: "ansible_nfs_from_fs"
        path: '/'
        filesystem_id: "fs_377"
        state: "present"

    - name: Create nfs export from snapshot
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_name: "ansible_nfs_from_snap"
        path: '/'
        snapshot_name: "ansible_fs_snap"
        state: "present"

    - name: Modify nfs export
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_name: "ansible_nfs_from_fs"
        nas_server_id: "nas_3"
        description: ""
        default_access: "READ_ONLY_ROOT"
        anonymous_gid: 4294967290
        anonymous_uid: 4294967290
        state: "present"

    - name: Add host in nfs export with adv_host_mgmt_enabled as true
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_name: "ansible_nfs_from_fs"
        filesystem_id: "fs_377"
        adv_host_mgmt_enabled: true
        no_access_hosts:
          - host_id: "Host_1"
        read_only_hosts:
          - host_id: "Host_2"
        read_only_root_hosts:
          - host_name: "host_name1"
        read_write_hosts:
          - host_name: "host_name2"
        read_write_root_hosts:
          - ip_address: "1.1.1.1"
        host_state: "present-in-export"
        state: "present"

    - name: Remove host in nfs export with adv_host_mgmt_enabled as true
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_name: "ansible_nfs_from_fs"
        filesystem_id: "fs_377"
        adv_host_mgmt_enabled: true
        no_access_hosts:
          - host_id: "Host_1"
        read_only_hosts:
          - host_id: "Host_2"
        read_only_root_hosts:
          - host_name: "host_name1"
        read_write_hosts:
          - host_name: "host_name2"
        read_write_root_hosts:
          - ip_address: "1.1.1.1"
        host_state: "absent-in-export"
        state: "present"

    - name: Add host in nfs export with adv_host_mgmt_enabled as false
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_name: "ansible_nfs_from_fs"
        filesystem_id: "fs_377"
        adv_host_mgmt_enabled: false
        no_access_hosts:
        - domain: "google.com"
        read_only_hosts:
        - netgroup: "netgroup_admin"
        read_only_root_hosts:
        - host_name: "host5"
        read_write_hosts:
        - subnet: "168.159.57.4/255.255.255.0"
        read_write_root_hosts:
        - ip_address: "10.255.2.4"
        host_state: "present-in-export"
        state: "present"

    - name: Remove host in nfs export with adv_host_mgmt_enabled as false
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_name: "ansible_nfs_from_fs"
        filesystem_id: "fs_377"
        adv_host_mgmt_enabled: false
        no_access_hosts:
        - domain: "google.com"
        read_only_hosts:
        - netgroup: "netgroup_admin"
        read_only_root_hosts:
        - host_name: "host5"
        read_write_hosts:
        - subnet: "168.159.57.4/255.255.255.0"
        read_write_root_hosts:
        - ip_address: "10.255.2.4"
        host_state: "absent-in-export"
        state: "present"

    - name: Get nfs details
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_id: "NFSShare_291"
        state: "present"

    - name: Delete nfs export by nfs name
      nfs:
        unispherehost: "{{unispherehost}}"
        username: "{{username}}"
        password: "{{password}}"
        validate_certs: "{{validate_certs}}"
        nfs_export_name: "ansible_nfs_name"
        nas_server_name: "ansible_nas_name"
        state: "absent"



Return Values
-------------

changed (always, bool, false)
  Whether or not the resource has changed.


nfs_share_details (When nfs export exists., dict, {'anonymous_gid': 4294967294, 'anonymous_uid': 4294967294, 'creation_time': '2022-03-09 15:05:34.720000+00:00', 'default_access': 'NFSShareDefaultAccessEnum.NO_ACCESS', 'description': '', 'export_option': 1, 'export_paths': ['**.***.**.**:/dummy-share-123'], 'filesystem': {'UnityFileSystem': {'id': 'fs_id_1', 'name': 'fs_name_1'}}, 'host_accesses': 'None', 'id': 'NFSShare_14393', 'is_read_only': 'None', 'min_security': 'NFSShareSecurityEnum.SYS', 'modification_time': '2022-04-25 08:12:28.179000+00:00', 'name': 'dummy-share-123', 'nfs_owner_username': 'None', 'no_access_hosts': 'None', 'no_access_hosts_string': 'host1,**.***.*.*', 'path': '/', 'read_only_hosts': 'None', 'read_only_hosts_string': '', 'read_only_root_access_hosts': 'None', 'read_only_root_hosts_string': '', 'read_write_hosts': 'None', 'read_write_hosts_string': '', 'read_write_root_hosts_string': '', 'role': 'NFSShareRoleEnum.PRODUCTION', 'root_access_hosts': 'None', 'snap': 'None', 'type': 'NFSTypeEnum.NFS_SHARE', 'existed': True, 'nas_server': {'UnityNasServer': {'id': 'nas_id_1', 'name': 'dummy_nas_server'}}})
  Details of the nfs export.


  anonymous_uid (, int, )
    User ID of the anonymous account


  anonymous_gid (, int, )
    Group ID of the anonymous account


  default_access (, str, )
    Default access level for all hosts that can access export


  description (, str, )
    Description about the nfs export


  id (, str, )
    ID of the nfs export


  min_security (, str, )
    NFS enforced security type for users accessing an export


  name (, str, )
    Name of the nfs export


  no_access_hosts_string (, str, )
    Hosts with no access to the nfs export


  read_only_hosts_string (, str, )
    Hosts with read-only access to the nfs export


  read_only_root_hosts_string (, str, )
    Hosts with read-only for root user access to the nfs export


  read_write_hosts_string (, str, )
    Hosts with read and write access to the nfs export


  read_write_root_hosts_string (, str, )
    Hosts with read and write for root user access to export


  type (, str, )
    NFS export type. i.e. filesystem or snapshot


  export_paths (, list, )
    Export paths that can be used to mount and access export


  filesystem (, dict, )
    Details of the filesystem on which nfs export is present


    UnityFileSystem (, dict, )
      filesystem details


      id (, str, )
        ID of the filesystem


      name (, str, )
        Name of the filesystem




  nas_server (, dict, )
    Details of the nas server


    UnityNasServer (, dict, )
      NAS server details


      id (, str, )
        ID of the nas server


      name (, str, )
        Name of the nas server








Status
------





Authors
~~~~~~~

- Vivek Soni (@v-soni11) <ansible.team@dell.com>