# Copyright: (c) 2023, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

DOCUMENTATION:
  module: debug_ldap_client
  short_description: Get host information for debugging LDAP connections
  description:
    - Get information about the current Ansible host to debug LDAP connections
      and their capabilities.
  version_added: 1.1.0
  options: {}
  notes:
    - See
      R(LDAP connection help,ansible_collections.microsoft.ad.docsite.guide_ldap_connection)
      for more information about LDAP connections.
    - The return values are not part of any contract and can change in the
      future. It is meant to give a snapshot of the Ansible host that can help
      debug LDAP connection issues and not be used as part of a normal playbook.
  extends_documentation_fragment:
    - ansible.builtin.action_common_attributes
    - ansible.builtin.action_common_attributes.flow
  attributes:
    check_mode:
      support: full
    diff_mode:
      support: none
    platform:
      platforms:
        - posix
    action:
      support: full
    async:
      support: full
    bypass_host_loop:
      support: none
  author:
    - Jordan Borean (@jborean93)

EXAMPLES: |
  - name: Get information about the Ansible host's LDAP capabilities
    microsoft.ad.debug_ldap_client:

RETURN:
  dns:
    description:
      - Details about the SRV LDAP server lookup.
      - The values will only be populated if dnspython is installed.
    returned: always
    type: complex
    contains:
      default_port:
        description:
          - The default port of the SRV record chosen.
        returned: dnspython is installed
        type: int
        sample: 389
      default_server:
        description:
          - The default hostname of the SRV record chosen.
        returned: dnspython is installed
        type: str
        sample: dc01.domain.com
      exception:
        description:
          - Any exceptions that occurred when getting the SRV records.
        returned: dnspython is installed
        type: str
        sample: ""
      records:
        description:
          - The SRV records that were found during the LDAP server lookup.
        returned: dnspython is installed
        type: list
        contains:
          port:
            description:
              - The port of this SRV record.
            returned: dnspython is installed and default_realm is found
            type: int
            sample: 389
          priority:
            description:
              - The record priority value.
            returned: dnspython is installed and default_realm is found
            type: int
            sample: 0
          target:
            description:
              - The target name of the SRV record.
            returned: dnspython is installed and default_realm is found
            type: str
            sample: dc01.domain.com.
          weight:
            description:
              - The record weight value.
            returned: dnspython is installed and default_realm is found
            type: int
            sample: 100
  kerberos:
    description:
      - Details about the host Kerberos setup.
      - The values will only be populated if krb5 is installed.
    returned: always
    type: complex
    contains:
      default_cc:
        description:
          - Details about the default Kerberos credential cache.
        returned: krb5 is installed
        type: complex
        contains:
          creds:
            description:
              - A list of credentials that is stored in the ccache.
              - This requires C(krb5 >= 0.5.0) to be populated.
            returned: krb5 is installed
            type: complex
            contains:
              client:
                description:
                  - The client principal name the credential is for.
                returned: krb5 >= 0.5.0 is installed
                type: str
                sample: username@DOMAIN.COM
              server:
                description:
                  - The server principal name the credential is for.
                returned: krb5 >= 0.5.0 is installed
                type: str
                sample: krbtgt/DOMAIN.COM@DOMAIN.COM
          exception:
            description:
              - Any exceptions that occurred when getting the ccache
                information.
            returned: krb5 is installed
            type: str
            sample: ""
          name:
            description:
              - The default ccache type and name.
            returned: krb5 is installed
            type: str
            sample: FILE:/tmp/krb5cc_1000
          principal:
            description:
              - The default principal of the ccache
            returned: krb5 is installed
            type: str
            sample: username@DOMAIN.COM
      default_realm:
        description:
          - The default_realm as reported by Kerberos.
          - This value is used for the automatic server lookup.
        returned: krb5 is installed
        type: str
        sample: domain.com
      exception:
        description:
          - Exception details if the default realm could not be retrieved.
        returned: krb5 is installed
        type: str
        sample: ""
  packages:
    description:
      - All the packages used by this collection for LDAP connections and their
        installed versions.
      - If the package is not installed, or failed to import, the value is the
        traceback from the import process.
      - This can be used to determine the availability of optional features like
        Kerberos authentication or server lookups.
    returned: always
    type: complex
    contains:
      dnspython:
        description:
          - The installed version of C(dnspython) or the import error if not
            installed.
        returned: always
        type: str
        sample: '2.3.0'
      dpapi_ng:
        description:
          - The installed version of C(dpapi-ng) or the import error if not
            installed.
        returned: always
        type: str
        sample: '0.1.0'
      krb5:
        description:
          - The installed version of C(krb5) or the import error if not
            installed.
        returned: always
        type: str
        sample: '0.5.0'
      pyspnego:
        description:
          - The installed version of C(pyspnego) or the import error if not
            installed.
        returned: always
        type: str
        sample: '0.8.0'
      sansldap:
        description:
          - The installed version of C(sansldap) or the import error if not
            installed.
        returned: always
        type: str
        sample: '0.1.0'
