### Get Filesystem Details

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/filesystem.rst

Example of retrieving details for a specific filesystem.

```APIDOC
## Get filesystem details

### Description
Retrieves the details of a specified filesystem.

### Parameters
#### Path Parameters
- **path** (str) - Required - The path of the filesystem.
- **access_zone** (str) - Optional - The access zone of the filesystem.

#### Request Body
- **state** (str) - Required - Set to 'present' to retrieve details.

### Connection Parameters
- **onefs_host** (str) - Required - IP address or FQDN of the PowerScale cluster.
- **port_no** (int) - Optional - Port number of the PowerScale cluster (defaults to 8080).
- **verify_ssl** (bool) - Optional - Whether to verify SSL certificate.
- **api_user** (str) - Required - Username for PowerScale cluster authentication.
- **api_password** (str) - Required - Password for PowerScale cluster authentication.

### Example
```yaml
- name: Get filesystem details
  dellemc.powerscale.filesystem:
    onefs_host: "{{onefs_host}}"
    port_no: "{{powerscaleport}}"
    verify_ssl: "{{verify_ssl}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    access_zone: "{{access_zone}}"
    path: "<path>"
    state: "{{state_present}}"
```
```

--------------------------------

### Get Filesystem Details with Snapshots

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/filesystem.rst

Example of retrieving filesystem details along with its snapshots.

```APIDOC
## Get filesystem details with snapshots

### Description
Retrieves the details of a specified filesystem, including its snapshots.

### Parameters
#### Path Parameters
- **path** (str) - Required - The path of the filesystem.
- **access_zone** (str) - Optional - The access zone of the filesystem.
- **list_snapshots** (bool) - Optional - If set to true, the filesystem's snapshots are returned.

#### Request Body
- **state** (str) - Required - Set to 'present' to retrieve details.

### Connection Parameters
- **onefs_host** (str) - Required - IP address or FQDN of the PowerScale cluster.
- **port_no** (int) - Optional - Port number of the PowerScale cluster (defaults to 8080).
- **verify_ssl** (bool) - Optional - Whether to verify SSL certificate.
- **api_user** (str) - Required - Username for PowerScale cluster authentication.
- **api_password** (str) - Required - Password for PowerScale cluster authentication.

### Example
```yaml
- name: Get filesystem details with snapshots
  dellemc.powerscale.filesystem:
    onefs_host: "{{onefs_host}}"
    port_no: "{{powerscaleport}}"
    verify_ssl: "{{verify_ssl}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    access_zone: "{{access_zone}}"
    path: "<path>"
    list_snapshots: "{{list_snapshots_true}}"
    state: "{{state_present}}"
```
```

--------------------------------

### Install PowerScale SDK

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/INSTALLATION.md

Installs the necessary Python SDK for interacting with PowerScale. Use this before building or managing collections.

```bash
pip install isilon-sdk
```

--------------------------------

### Get Role

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/role.rst

This example shows how to retrieve details of an existing authentication role.

```APIDOC
## Get Role

### Description
Retrieves details of a specific authentication role from the PowerScale system.

### Method
GET (implicitly via Ansible module)

### Endpoint
Not directly applicable (Ansible module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
Parameters are passed as module arguments:
- **onefs_host** (str, required): IP address or FQDN of the PowerScale cluster.
- **api_user** (str, required): Username for PowerScale cluster authentication.
- **api_password** (str, required): Password for PowerScale cluster authentication.
- **verify_ssl** (bool, required): Specifies whether to validate the SSL certificate.
- **role_name** (str, required): Name of the Auth Role to retrieve.
- **access_zone** (str, optional): The access zone in which the auth role exists. Defaults to 'System'.

### Request Example
```yaml
- name: Get Role
  dellemc.powerscale.role:
    onefs_host: "{{onefs_host}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    verify_ssl: "{{verify_ssl}}"
    role_name: "Test_Role"
    access_zone: "{{access_zone}}"
```

### Response
#### Success Response (200)
Details of the requested role (structure not specified in source).

#### Response Example
(Not specified in source)
```

--------------------------------

### Install PowerScale Ansible Collection and SDK

Source: https://context7.com/dell/ansible-powerscale/llms.txt

Install the necessary Python SDK and the Ansible collection from Galaxy. You can also build and install from source. Set the collections path if installing to a custom location.

```bash
# Install the SDK dependency
pip install isilon-sdk

# Install the collection from Ansible Galaxy
ansible-galaxy collection install dellemc.powerscale -p <install_path>

# Or build and install from source
ansible-galaxy collection build
ansible-galaxy collection install dellemc-powerscale-3.9.1.tar.gz -p <install_path>

# Set collections path if installing to a custom location
export ANSIBLE_COLLECTIONS_PATHS=$ANSIBLE_COLLECTIONS_PATHS:<install_path>

# View documentation for any module
ansible-doc dellemc.powerscale.info
```

--------------------------------

### Create Filesystem with Access Control for Everyone

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/filesystem.rst

This example shows how to create a filesystem and grant access control rights to 'everyone'.

```APIDOC
## Create Filesystem with Access Control for Everyone

### Description
Creates a filesystem and applies access control rights for the 'everyone' trustee.

### Parameters
#### Path Parameters
- **onefs_host** (str) - Required - The hostname or IP address of the OneFS cluster.
- **port_no** (int) - Optional - The port number for the API.
- **verify_ssl** (bool) - Optional - Whether to verify SSL certificates.
- **api_user** (str) - Required - The username for API authentication.
- **api_password** (str) - Required - The password for API authentication.
- **path** (str) - Required - The path to the filesystem.
- **access_zone** (str) - Required - The access zone of the filesystem.

#### Request Body
- **access_control_rights** (list) - Required - A list of access control right configurations.
  - **access_type** (str) - Required - The type of access (e.g., 'allow').
  - **access_rights** (list) - Required - A list of specific access rights (e.g., ['dir_gen_all']).
  - **inherit_flags** (list) - Optional - Flags for inheritance (e.g., ['container_inherit']).
  - **trustee** (dict) - Required - The trustee configuration.
    - **name** (str) - Required - The name of the trustee ('everyone').
    - **type** (str) - Required - The type of the trustee ('wellknown').
- **access_control_rights_state** (str) - Required - The state of the access control rights ('add').
- **state** (str) - Required - The desired state of the filesystem ('present').
```

--------------------------------

### Create and configure a network pool

Source: https://context7.com/dell/ansible-powerscale/llms.txt

This example shows how to create a new network pool with specified IP ranges, interface bindings, and SmartConnect parameters. The `state: "present"` ensures the pool is created or updated if it exists.

```yaml
- name: Create and configure a network pool
  dellemc.powerscale.networkpool:
    onefs_host: "10.1.1.1"
    api_user: "root"
    api_password: "secret"
    verify_ssl: false
    groupnet_name: "groupnet0"
    subnet_name: "subnet0"
    pool_name: "client_pool_1"
    description: "Client access pool"
    additional_pool_params:
      ranges:
        - low: "192.168.10.100"
          high: "192.168.10.120"
      range_state: "add"
      ifaces:
        - iface: "ext-1"
          lnn: 1
        - iface: "ext-2"
          lnn: 2
      iface_state: "add"
    sc_params:
      sc_connect_policy: "round_robin"
      sc_failover_policy: "round_robin"
      rebalance_policy: "auto"
      alloc_method: "static"
      sc_dns_zone: "client-pool.example.com"
      aggregation_mode: "roundrobin"
    state: "present"
```

--------------------------------

### Get groupnet details

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/groupnet.rst

Example of retrieving details of a specific groupnet.

```APIDOC
## Get groupnet details

### Description
Retrieves the configuration details of a specified groupnet.

### Method
GET (Implicit)

### Endpoint
/groupnet/{groupnet_name}

### Parameters
#### Path Parameters
- **groupnet_name** (str) - Required - The name of the groupnet to retrieve details for.

#### Query Parameters
None

#### Request Body
- **one_fs_host** (str) - Required - IP address or FQDN of the PowerScale cluster.
- **port_no** (int) - Optional - Port number of the PowerScale cluster. Defaults to 8080.
- **api_user** (str) - Required - Username for authentication.
- **api_password** (str) - Required - Password for authentication.

### Request Example
```yaml
- name: Get groupnet details
  dellemc.powerscale.groupnet:
    onefs_host: "{{onefs_host}}"
    port_no: "{{port_no}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
```

### Response
#### Success Response (200)
Returns a JSON object containing the details of the specified groupnet.

#### Response Example
```json
{
  "id": "1",
  "name": "groupnet_test",
  "description": "Test Groupnet",
  "dns_servers": [
    "198.10.***.***"
  ],
  "dns_search_suffix": [
    "samplesearch.com"
  ]
}
```
```

--------------------------------

### Get NFS Export

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/nfs.rst

Example of retrieving information about an existing NFS export.

```APIDOC
## Get NFS Export

### Description
Retrieves the configuration of an existing NFS export.

### Method
`dellemc.powerscale.nfs`

### Parameters
#### Path Parameters
- **path** (str) - Required - The path for the NFS export.
- **access_zone** (str) - Required - The access zone for the NFS export.

#### Query Parameters
- **onefs_host** (str) - Required - IP address or FQDN of the PowerScale cluster.
- **api_user** (str) - Required - Username for PowerScale cluster authentication.
- **api_password** (str) - Required - Password for PowerScale cluster authentication.
- **verify_ssl** (bool) - Optional - Specifies whether to validate the SSL certificate. Defaults to true.
- **state** (str) - Optional - Defines whether the NFS export should exist. Accepted values: 'present', 'absent'. Defaults to 'present'.

### Request Example
```yaml
- name: Get NFS Export
  dellemc.powerscale.nfs:
    onefs_host: "{{onefs_host}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    verify_ssl: "{{verify_ssl}}"
    path: "<path>"
    access_zone: "{{access_zone}}"
    state: 'present'
```
```

--------------------------------

### Set up Virtual Environment

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/DEVELOPERS_GUIDE.md

Creates a virtual environment and installs necessary dependencies for the Ansible collection development.

```bash
cd /root/ansible_collections/dellemc/powerscale
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt -r tests/unit/requirements.txt ansible-lint ansible-core
```

--------------------------------

### Create New Network Provisioning Rule

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/networkrule.rst

This example demonstrates how to create a new network provisioning rule. It includes parameters for rule name, description, interface, node type, and state.

```yaml
- name: Create a new network provisioning rule
  dellemc.powerscale.networkrule:
    onefs_host: "{{onefs_host}}"
    port_no: "{{port_no}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    verify_ssl: "{{verify_ssl}}"
    groupnet_name: "groupnet1"
    subnet_name: "subnet1"
    pool_name: "pool1"
    rule_name: "new_rule"
    description: "Rename existing rule"
    iface: "ext1"
    node_type: "storage"
    state: "present"
```

--------------------------------

### Get Network Pool

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/networkpool.rst

This example demonstrates how to retrieve information about a specific network pool.

```APIDOC
## Get Network Pool

### Description
Retrieves details of a specified network pool.

### Method
`dellemc.powerscale.networkpool`

### Parameters
- `onefs_host` (str) - Required - The IP address or hostname of the OneFS cluster.
- `api_user` (str) - Required - The username for API authentication.
- `api_password` (str) - Required - The password for API authentication.
- `verify_ssl` (bool) - Optional - Whether to verify SSL certificates.
- `groupnet_name` (str) - Required - The name of the groupnet.
- `subnet_name` (str) - Required - The name of the subnet.
- `pool_name` (str) - Required - The name of the network pool to retrieve.
- `state` (str) - Required - Set to "present" to get the pool details.

### Request Example
```yaml
- name: Get Network Pool
  dellemc.powerscale.networkpool:
    onefs_host: "{{onefs_host}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    verify_ssl: "{{verify_ssl}}"
    groupnet_name: "groupnet0"
    subnet_name: "subnet0"
    pool_name: "Test_Pool_2"
    state: "present"
```
```

--------------------------------

### Create a default-directory Quota with description and labels

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/smartquota.rst

This example demonstrates creating a default-directory quota with specific thresholds, description, and labels. The `state` parameter must be `present`.

```APIDOC
## Create a default-directory Quota with description and labels

### Description
Creates a default directory quota with specified thresholds, description, and labels.

### Parameters
- `onefs_host` (str) - Required - The hostname or IP address of the OneFS cluster.
- `verify_ssl` (bool) - Optional - Whether to verify SSL certificates.
- `api_user` (str) - Required - The username for API authentication.
- `api_password` (str) - Required - The password for API authentication.
- `path` (str) - Required - The directory path for the quota.
- `quota_type` (str) - Required - The type of quota, must be 'default-directory'.
- `description` (str) - Optional - A description for the quota.
- `labels` (str) - Optional - Comma-separated labels for the quota.
- `quota` (dict) - Required - Quota configuration.
  - `thresholds_on` (str) - Optional - The metric on which thresholds are based (e.g., 'fs_logical_size').
  - `hard_limit_size` (int) - Required - The hard limit size for the quota.
  - `cap_unit` (str) - Required - The unit for the capacity limit (e.g., 'TB').
  - `include_snapshots` (bool) - Optional - Whether to include snapshots in the quota calculation.
- `state` (str) - Required - Set to `present` to create or update the quota.
```

--------------------------------

### Get LDAP provider details

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/ldap.rst

This example shows how to retrieve the details of an LDAP provider.

```APIDOC
## Get LDAP provider details

### Description
This task retrieves the details of a specified LDAP provider.

### Method
GET

### Endpoint
/api/v1/auth/providers/ldap/{ldap_name}

### Parameters
#### Path Parameters
- **ldap_name** (str) - Required - The name of the LDAP provider to retrieve details for.

#### Query Parameters
None

#### Request Body
None

### Request Example
```yaml
- name: Get LDAP provider details
  dellemc.powerscale.ldap:
    onefs_host: "{{onefs_host}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
```

### Response
#### Success Response (200)
- **ldap_name** (str) - The name of the LDAP provider.
- **server_uris** (list) - A list of server URIs configured for the provider.
- **base_dn** (str) - The base DN for LDAP searches.
- **ldap_parameters** (dict) - Additional LDAP parameters.
  - **groupnet** (str) - The groupnet identifier.
  - **bind_dn** (str) - The distinguished name used for binding.
- **state** (str) - The current state of the LDAP provider.
```

--------------------------------

### Create SMB share for system access zone with advanced options

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/smb.rst

This example demonstrates creating an SMB share within a system access zone, configuring advanced features like file filtering, continuous availability, and encryption. It also includes host access control lists.

```yaml
- name: Create SMB share for system access zone
  dellemc.powerscale.smb:
    onefs_host: "{{onefs_host}}"
    verify_ssl: "{{verify_ssl}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    share_name: "{{name}}"
    path: "{{system_az_path}}"
    description: "{{description}}"
    create_path: false
    allow_variable_expansion: true
    auto_create_directory: true
    continuously_available: true
    file_filter_extension:
      extensions:
        - "sample_extension_1"
      type: "allow"
      state: "present-in-share"
    file_filtering_enabled: true
    ca_timeout:
      value: 60
      unit: "minutes"
    strict_ca_lockout: true
    smb3_encryption_enabled: true
    ca_write_integrity: "write-read-coherent"
    change_notify: "all"
    oplocks: true
    impersonate_guest: "never"
    impersonate_user: "sample_user"
    host_acls:
      - name: "sample_host_acl_1"
        access_type: "allow"
      - name: "sample_host_acl_2"
        access_type: "deny"
    state: "present"
```

--------------------------------

### Create Filesystem without Quota

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/filesystem.rst

This example shows how to create a filesystem in the default access zone without configuring any quotas. It requires basic connection and path information.

```yaml
- name: Create Filesystem in default (system) access zone, without Quota
  dellemc.powerscale.filesystem:
    onefs_host: "{{onefs_host}}"
    port_no: "{{powerscaleport}}"
    verify_ssl: "{{verify_ssl}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    path: "<path>"
    owner:
      name: 'ansible_user'
      provider_type: 'ldap'
    state: "{{state_present}}"
```

--------------------------------

### Configure All IPMI Domains at Once

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/ipmi.rst

This example shows how to configure all IPMI settings, including network and user details, simultaneously.

```APIDOC
## Configure all IPMI domains at once

### Description
Configures all IPMI settings, including features, network, and user credentials, in a single operation.

### Method
dellemc.powerscale.ipmi

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **onefs_host** (string) - Required - The hostname or IP address of the OneFS cluster.
- **port_no** (integer) - Optional - The port number for IPMI communication.
- **api_user** (string) - Required - The username for API authentication.
- **api_password** (string) - Required - The password for API authentication.
- **verify_ssl** (boolean) - Optional - Whether to verify SSL certificates.
- **settings** (dict) - Optional - IPMI settings.
  - **enabled** (boolean) - Required - Whether remote IPMI management is enabled.
  - **allocation_type** (string) - Required - The IP allocation type for IPMI (e.g., "static", "dhcp").
- **network** (dict) - Optional - IPMI network configuration.
  - **gateway** (string) - Required - The gateway IP address for the IPMI network.
  - **prefixlen** (integer) - Required - The network prefix length for the IPMI network.
  - **ip_ranges** (list) - Optional - List of IP address ranges for IPMI.
    - **low** (string) - Required - The low end of the IP address range.
    - **high** (string) - Required - The high end of the IP address range.
- **user** (dict) - Optional - IPMI user configuration.
  - **username** (string) - Required - The BMC username.
  - **password** (string) - Required - The BMC password.
- **features** (list) - Required - A list of features to configure.
  - **id** (string) - Required - The feature identifier (e.g., "power_control", "sol").
  - **enabled** (boolean) - Required - Whether to enable the feature.
- **state** (string) - Optional - The desired state of the IPMI configuration (e.g., "present").

### Request Example
```yaml
- name: Configure all IPMI domains at once
  dellemc.powerscale.ipmi:
    onefs_host: "{{ onefs_host }}"
    port_no: "{{ port_no }}"
    api_user: "{{ api_user }}"
    api_password: "{{ api_password }}"
    verify_ssl: "{{ verify_ssl }}"
    settings:
      enabled: true
      allocation_type: "static"
    network:
      gateway: "10.0.0.1"
      prefixlen: 24
      ip_ranges:
        - low: "10.0.0.100"
          high: "10.0.0.200"
    user:
      username: "admin"
      password: "{{ vault_ipmi_password }}"
    features:
      - id: "power_control"
        enabled: true
      - id: "sol"
        enabled: true
    state: "present"
```

### Response
#### Success Response (200)
- **changed** (boolean) - Indicates if changes were made.
- **diff** (dict) - Differences between before and after states (if diff mode is enabled).
- **ipmi_details** (dict) - The current IPMI configuration.

#### Response Example
```json
{
  "changed": true,
  "diff": {
    "after": {
      "features": [
        {
          "enabled": true,
          "id": "power_control"
        },
        {
          "enabled": true,
          "id": "sol"
        }
      ],
      "network": {
        "gateway": "10.0.0.1",
        "prefixlen": 24
      },
      "settings": {
        "allocation_type": "static",
        "enabled": true
      },
      "user": {
        "username": "admin"
      }
    },
    "before": {
      "features": [
        {
          "enabled": false,
          "id": "power_control"
        }
      ],
      "network": {
        "gateway": "",
        "prefixlen": 0
      },
      "settings": {
        "allocation_type": "dhcp",
        "enabled": false
      },
      "user": {
        "username": "admin"
      }
    }
  },
  "ipmi_details": {
    "features": [
      {
        "enabled": true,
        "id": "power_control"
      },
      {
        "enabled": true,
        "id": "sol"
      }
    ],
    "network": {
      "gateway": "10.0.0.1",
      "ip_ranges": [
        {
          "high": "10.0.0.200",
          "low": "10.0.0.100"
        }
      ],
      "prefixlen": 24
    },
    "settings": {
      "allocation_type": "static",
      "enabled": true
    },
    "user": {
      "username": "admin"
    }
  }
}
```
```

--------------------------------

### Get Alert Channel Details

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/alert_channel.rst

This example shows how to retrieve the details of an existing alert channel.

```APIDOC
## Get Alert Channel Details

### Description
Retrieves the details of a specified alert channel.

### Method
Uses the `dellemc.powerscale.alert_channel` module with `state: "present"` and without specifying parameters that modify the channel.

### Parameters
- **onefs_host** (str) - Required - The IP address or hostname of the PowerScale cluster.
- **port_no** (int) - Required - The HTTPS port of the PowerScale cluster.
- **api_user** (str) - Required - The username for API authentication.
- **api_password** (str) - Required - The password for API authentication.
- **verify_ssl** (bool) - Optional - Whether to verify SSL certificates. Defaults to true.
- **name** (str) - Required - The name of the alert channel to retrieve details for.

### Request Example
```yaml
- name: Get the alert channel details
  dellemc.powerscale.alert_channel:
    onefs_host: "{{ onefs_host }}"
    port_no: "{{ port_no }}"
    api_user: "{{ api_user }}"
    api_password: "{{ api_password }}"
    verify_ssl: "{{ verify_ssl }}"
    name: "sample_event_channel"
    state: "present"
```

### Response
#### Success Response (200)
- **changed** (bool) - Indicates if changes were made (will be false if only retrieving details).
- **alert_channel_details** (dict) - Details of the alert channel.
  - **allowed_nodes** (list)
  - **enabled** (bool)
  - **excluded_nodes** (list)
  - **id** (str)
  - **name** (str)
  - **parameters** (dict)
  - **rules** (list)
  - **system** (bool)
  - **type** (str)

#### Response Example
```json
{
  "changed": false,
  "alert_channel_details": {
    "allowed_nodes": [1, 2],
    "enabled": true,
    "excluded_nodes": [3],
    "id": "1",
    "name": "sample_event_channel",
    "parameters": {
      "address": ["sample.com"],
      "batch": "ALL",
      "batch_period": 120,
      "custom_template": "sample",
      "send_as": "test@sample.com",
      "smtp_host": "sample.com",
      "smtp_password": "sample_password",
      "smtp_port": 25,
      "smtp_security": "none",
      "smtp_use_auth": false,
      "smtp_username": "sample-user",
      "subject": "sample"
    },
    "rules": [],
    "system": false,
    "type": "smtp"
  }
}
```
```

--------------------------------

### Get Active Directory provider details

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/ads.rst

This example retrieves the details of an Active Directory provider using its domain name.

```APIDOC
## Get Active Directory provider details

### Description
Retrieves the details of an Active Directory provider from the PowerScale cluster.

### Method
GET (implicitly via Ansible module)

### Endpoint
N/A (Ansible module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **onefs_host** (string) - Required - The hostname or IP address of the PowerScale cluster.
- **api_user** (string) - Required - The username for API authentication.
- **api_password** (string) - Required - The password for API authentication.
- **verify_ssl** (bool) - Optional - Whether to verify SSL certificates.
- **domain_name** (string) - Required - The domain name of the Active Directory provider.
- **state** (string) - Required - Set to "present" to get details.
```

--------------------------------

### smb_file Module Usage

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/smb_file.rst

Examples demonstrating how to use the smb_file module to manage SMB files.

```APIDOC
## Get list of SMB files of the PowerScale cluster

### Description
Retrieves a list of all open SMB files on the PowerScale cluster.

### Method
`dellemc.powerscale.smb_file`

### Parameters
#### Required
- **onefs_host** (str) - IP address or FQDN of the PowerScale cluster.
- **api_user** (str) - Username of the PowerScale cluster.
- **api_password** (str) - Password of the PowerScale cluster.

#### Optional
- **port_no** (str) - Port number of the PowerScale cluster. Defaults to 8080.
- **verify_ssl** (bool) - Whether to validate SSL certificate. Defaults to True.
- **state** (str) - Defines the state of SMB file. Defaults to 'present'.

### Request Example
```yaml
- name: Get list of SMB files of the PowerScale cluster
  dellemc.powerscale.smb_file:
    onefs_host: "{{onefs_host}}"
    verify_ssl: "{{verify_ssl}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    state: "present"
```

## Close SMB file by ID

### Description
Closes a specific SMB open file session identified by its unique ID.

### Method
`dellemc.powerscale.smb_file`

### Parameters
#### Required
- **onefs_host** (str) - IP address or FQDN of the PowerScale cluster.
- **api_user** (str) - Username of the PowerScale cluster.
- **api_password** (str) - Password of the PowerScale cluster.
- **file_id** (int) - Unique ID of the SMB open file.

#### Optional
- **port_no** (str) - Port number of the PowerScale cluster. Defaults to 8080.
- **verify_ssl** (bool) - Whether to validate SSL certificate. Defaults to True.
- **state** (str) - Defines the state of SMB file. Must be 'absent' to close the file.

### Request Example
```yaml
- name: Close SMB file of the PowerScale cluster
  dellemc.powerscale.smb_file:
    onefs_host: "{{onefs_host}}"
    verify_ssl: "{{verify_ssl}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    file_id: xxx
    state: "absent"
```

## Close SMB file by Path

### Description
Closes all open SMB file sessions within a specified file path.

### Method
`dellemc.powerscale.smb_file`

### Parameters
#### Required
- **onefs_host** (str) - IP address or FQDN of the PowerScale cluster.
- **api_user** (str) - Username of the PowerScale cluster.
- **api_password** (str) - Password of the PowerScale cluster.
- **file_path** (str) - Path of the SMB file.

#### Optional
- **port_no** (str) - Port number of the PowerScale cluster. Defaults to 8080.
- **verify_ssl** (bool) - Whether to validate SSL certificate. Defaults to True.
- **state** (str) - Defines the state of SMB file. Must be 'absent' to close the file.

### Request Example
```yaml
- name: Close smb file of the PowerScale cluster
  dellemc.powerscale.smb_file:
    onefs_host: "{{onefs_host}}"
    verify_ssl: "{{verify_ssl}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    file_path: "/ifs/ATest"
    state: "absent"
```

### Return Values

- **changed** (bool) - A boolean indicating if the task had to make changes.
- **smb_file_details** (dict) - The SMB file details. Contains a list of dictionaries, each representing an open SMB file with its properties like 'file', 'id', 'locks', 'permissions', and 'user'.
```

--------------------------------

### Create a Quota with percent-based thresholds and force

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/smartquota.rst

This example shows how to create a directory quota using percent-based thresholds and enabling the `force` option. The `state` parameter must be `present`.

```APIDOC
## Create a Quota with percent-based thresholds and force

### Description
Creates a directory quota with percent-based thresholds and the force option enabled.

### Parameters
- `onefs_host` (str) - Required - The hostname or IP address of the OneFS cluster.
- `verify_ssl` (bool) - Optional - Whether to verify SSL certificates.
- `api_user` (str) - Required - The username for API authentication.
- `api_password` (str) - Required - The password for API authentication.
- `path` (str) - Required - The directory path for the quota.
- `quota_type` (str) - Required - The type of quota (e.g., 'directory').
- `force` (bool) - Optional - If true, forces the creation or update of the quota.
- `quota` (dict) - Required - Quota configuration.
  - `thresholds_on` (str) - Optional - The metric on which thresholds are based (e.g., 'fs_logical_size').
  - `hard_limit_size` (int) - Required - The hard limit size for the quota.
  - `cap_unit` (str) - Required - The unit for the capacity limit (e.g., 'TB').
  - `percent_soft` (float) - Optional - The soft limit as a percentage.
  - `percent_advisory` (float) - Optional - The advisory limit as a percentage.
  - `soft_grace_period` (int) - Optional - The grace period for the soft limit in days.
  - `period_unit` (str) - Optional - The unit for the grace period (e.g., 'days').
  - `include_snapshots` (bool) - Optional - Whether to include snapshots in the quota calculation.
- `state` (str) - Required - Set to `present` to create or update the quota.
```

--------------------------------

### Job Management Operations

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/job.rst

Examples demonstrating various job management operations like starting, pausing, resuming, and cancelling jobs.

```APIDOC
## Start a SmartPools job

### Description
Starts a new SmartPools job with specified paths and priority.

### Method
POST (implied by module usage)

### Endpoint
Not explicitly defined, module operates on PowerScale API.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (parameters are passed to the module)

### Request Example
```yaml
- name: Start a SmartPools job
  dellemc.powerscale.job:
    onefs_host: "{{ onefs_host }}"
    port_no: "{{ port_no }}"
    api_user: "{{ api_user }}"
    api_password: "{{ api_password }}"
    verify_ssl: "{{ verify_ssl }}"
    job_type: "SmartPools"
    paths:
      - "/ifs/data"
    priority: 5
    state: "present"
```

## Start a TreeDelete job and wait for completion

### Description
Starts a new TreeDelete job with specified paths and waits for its completion.

### Method
POST (implied by module usage)

### Endpoint
Not explicitly defined, module operates on PowerScale API.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (parameters are passed to the module)

### Request Example
```yaml
- name: Start a TreeDelete job and wait for completion
  dellemc.powerscale.job:
    onefs_host: "{{ onefs_host }}"
    port_no: "{{ port_no }}"
    api_user: "{{ api_user }}"
    api_password: "{{ api_password }}"
    verify_ssl: "{{ verify_ssl }}"
    job_type: "TreeDelete"
    paths:
      - "/ifs/data/old_dir"
    wait: true
    wait_timeout: 600
    wait_interval: 15
    state: "present"
```

## Pause a running job

### Description
Pauses a running job identified by its ID.

### Method
POST (implied by module usage)

### Endpoint
Not explicitly defined, module operates on PowerScale API.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (parameters are passed to the module)

### Request Example
```yaml
- name: Pause a running job
  dellemc.powerscale.job:
    onefs_host: "{{ onefs_host }}"
    port_no: "{{ port_no }}"
    api_user: "{{ api_user }}"
    api_password: "{{ api_password }}"
    verify_ssl: "{{ verify_ssl }}"
    job_id: 12345
    job_state: "paused"
    state: "present"
```

## Resume a paused job

### Description
Resumes a paused job identified by its ID.

### Method
POST (implied by module usage)

### Endpoint
Not explicitly defined, module operates on PowerScale API.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (parameters are passed to the module)

### Request Example
```yaml
- name: Resume a paused job
  dellemc.powerscale.job:
    onefs_host: "{{ onefs_host }}"
    port_no: "{{ port_no }}"
    api_user: "{{ api_user }}"
    api_password: "{{ api_password }}"
    verify_ssl: "{{ verify_ssl }}"
    job_id: 12345
    job_state: "running"
    state: "present"
```

## Cancel a running job

### Description
Cancels a running or paused job identified by its ID.

### Method
POST (implied by module usage)

### Endpoint
Not explicitly defined, module operates on PowerScale API.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (parameters are passed to the module)

### Request Example
```yaml
- name: Cancel a running job
  dellemc.powerscale.job:
    onefs_host: "{{ onefs_host }}"
    port_no: "{{ port_no }}"
    api_user: "{{ api_user }}"
    api_password: "{{ api_password }}"
    verify_ssl: "{{ verify_ssl }}"
    job_id: 12345
    job_state: "cancelled"
    state: "present"
```
```

--------------------------------

### Get Active Directory provider details by instance name

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/ads.rst

This example retrieves the details of an Active Directory provider using its instance name.

```APIDOC
## Get Active Directory provider details by instance name

### Description
Retrieves the details of an Active Directory provider from the PowerScale cluster using its instance name.

### Method
GET (implicitly via Ansible module)

### Endpoint
N/A (Ansible module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **onefs_host** (string) - Required - The hostname or IP address of the PowerScale cluster.
- **api_user** (string) - Required - The username for API authentication.
- **api_password** (string) - Required - The password for API authentication.
- **verify_ssl** (bool) - Optional - Whether to verify SSL certificates.
- **instance_name** (string) - Required - The instance name of the Active Directory provider.
- **state** (string) - Required - Set to "present" to get details.
```

--------------------------------

### Create or Modify Filesystem with Quota

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/filesystem.rst

This example demonstrates how to create or modify a filesystem and set a quota with a hard limit.

```APIDOC
## Create or Modify Filesystem with Quota

### Description
Manages a filesystem with specified quota settings.

### Parameters
#### Path Parameters
- **onefs_host** (str) - Required - The hostname or IP address of the OneFS cluster.
- **port_no** (int) - Optional - The port number for the API.
- **verify_ssl** (bool) - Optional - Whether to verify SSL certificates.
- **api_user** (str) - Required - The username for API authentication.
- **api_password** (str) - Required - The password for API authentication.
- **path** (str) - Required - The path to the filesystem.
- **access_zone** (str) - Required - The access zone of the filesystem.

#### Request Body
- **quota** (dict) - Optional - Quota configuration.
  - **hard_limit_size** (int) - Required - The hard limit size for the quota.
  - **cap_unit** (str) - Optional - The unit for the hard limit size (e.g., "GB").
  - **quota_state** (str) - Required - The state of the quota ('present' or 'absent').
  - **container** (bool) - Optional - Whether the quota applies to containers.
- **state** (str) - Required - The desired state of the filesystem ('present' or 'absent').
```

--------------------------------

### Get a single SyncIQ target report by Name

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/synciqtargetreports.rst

This example demonstrates how to fetch a SyncIQ target report by its name. It requires the same connection parameters as fetching by ID.

```yaml
- name: Get a single SyncIQ target report with name
  dellemc.powerscale.synciqtargetreports:
    onefs_host: "{{onefs_host}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    verify_ssl: "{{verify_ssl}}"
    name: "sample_policy"
    state: "present"
```

--------------------------------

### Get SyncIQ Report by Name

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/synciqreports.rst

This example demonstrates how to fetch a SyncIQ report by its name. Provide the PowerScale host, API credentials, and SSL verification details.

```yaml
- name: Get a single SyncIQ report with name
  dellemc.powerscale.synciqreports:
    onefs_host: "{{onefs_host}}"
    api_user: "{{api_user}}"
    api_password: "{{api_password}}"
    verify_ssl: "{{verify_ssl}}"
    name: "Test_snap_schedule_123"
    state: "present"
```

--------------------------------

### Create a SyncIQ policy

Source: https://github.com/dell/ansible-powerscale/blob/main/docs/modules/synciqpolicy.rst

This example demonstrates how to create a SyncIQ policy with various configuration options, including source and target cluster details, snapshot settings, and network restrictions.

```APIDOC
## Create a SyncIQ policy

### Description
Creates a SyncIQ policy with specified source and target cluster configurations, snapshot settings, and other policy parameters.

### Parameters
- **onefs_host** (string) - Required - The hostname or IP address of the OneFS cluster.
- **api_user** (string) - Required - The username for API authentication.
- **api_password** (string) - Required - The password for API authentication.
- **verify_ssl** (bool) - Required - Whether to verify SSL certificates.
- **run_job** (string) - Optional - Specifies when to run the job (e.g., "when-snapshot-taken").
- **snapshot_sync_patten** (string) - Optional - Regex pattern for snapshot synchronization.
- **source_cluster** (dict) - Required - Configuration for the source cluster.
  - **source_root_path** (string) - Required - Path to the source directory.
  - **source_exclude_directories** (string) - Optional - Directories to exclude from synchronization.
  - **source_include_directories** (string) - Optional - Directories to include in synchronization.
  - **source_network** (dict) - Optional - Network configuration for the source.
    - **pool** (string) - Required - The network pool to use.
    - **subnet** (string) - Required - The subnet to use.
- **target_cluster** (dict) - Required - Configuration for the target cluster.
  - **target_host** (string) - Required - Hostname or IP of the target cluster.
  - **target_path** (string) - Required - Path to the target directory.
  - **target_certificate_id** (string) - Optional - ID of the certificate for target cluster.
- **target_snapshot** (dict) - Optional - Configuration for target snapshots.
  - **target_snapshot_archive** (bool) - Optional - Whether to archive target snapshots.
- **accelerated_failback** (bool) - Optional - Enable accelerated failback.
- **restrict_target_network** (bool) - Optional - Restrict network access on the target.
- **target_compare_initial_sync** (bool) - Optional - Compare target during initial sync.
- **state** (string) - Required - The desired state of the policy ('present' or 'absent').

### Request Example
```json
{
  "onefs_host": "{{onefs_host}}",
  "api_user": "{{api_user}}",
  "api_password": "{{api_password}}",
  "verify_ssl": "{{verify_ssl}}",
  "run_job": "when-snapshot-taken",
  "snapshot_sync_patten": "^snapshot\-$latest",
  "source_cluster": {
    "source_root_path": "<path_to_source>",
    "source_exclude_directories": "<path_to_exclude>",
    "source_include_directories": "<path_to_include>",
    "source_network": {
      "pool": "pool1",
      "subnet": "subnet1"
    }
  },
  "target_cluster": {
    "target_host": "198.10.xxx.xxx",
    "target_path": "<path_to_target>",
    "target_certificate_id": "7sdgvejkiau7629903048hdjdkljsbwgsuasj716iuhywthsjk"
  },
  "target_snapshot": {
    "target_snapshot_archive": false
  },
  "accelerated_failback": true,
  "restrict_target_network": false,
  "target_compare_initial_sync": false,
  "state": "present"
}
```
```