Repository: ansible-collections/community.general

Issue:
community.general.ldap_search does not support the "subtree" scope; no way to search a whole LDAP tree with ldap_search
### Summary

The community.general.ldap_search module does not support the "subtree" scope.  Although this module does support the "subordinate" scope, the "subordinate" scope is not supported by default on most popular LDAP server implementations, such as Active Directory or OpenLDAP.

Without support for the "subtree" scope, there is no way to use this module to search an entire LDAP tree on such LDAP servers.  This limits searches to objects where the full DN or parent container of the object(s) being searched for are already known.

I am filing this as a bug report rather than a feature request since this seems like a bizarrely basic feature to be missing from an ldap search tool.

I believe this to be related to #4894 , although it seems that the OP in that issue may not have understood the difference between the "subordinate" and "subtree" scopes.

### Issue Type

Bug Report

### Component Name

ldap_search

### Ansible Version

```console (paste below)
(ansible-venv) [turducken ~/Work/git/or-ldap](master|✔)[I]% ansible --version
ansible [core 2.15.3]
  config file = /media/psf/Home/Work/git/or-ldap/ansible.cfg
  configured module search path = ['/home/jay/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /media/psf/Home/Work/ansible-venv/lib/python3.10/site-packages/ansible
  ansible collection location = /home/jay/.ansible/collections:/usr/share/ansible/collections
  executable location = /media/psf/Home/Work/ansible-venv/bin/ansible
  python version = 3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0] (/media/psf/Home/Work/ansible-venv/bin/python3)
  jinja version = 3.1.2
  libyaml = True
```


### Community.general Version

```console (paste below)
(ansible-venv) [turducken ~/Work/git/or-ldap](master|✔)[I]% ansible-galaxy collection list community.general

# /media/psf/Home/Work/ansible-venv/lib/python3.10/site-packages/ansible_collections
Collection        Version
----------------- -------
community.general 7.3.0  
```


### Configuration

n/a

### OS / Environment

n/a

### Steps to Reproduce

n/a

### Expected Results

n/a

### Actual Results

n/a


### Code of Conduct

- [X] I agree to follow the Ansible Code of Conduct


Discussion:
Files identified in the description:
* [`plugins/modules/ldap_search.py`](https://github.com/ansible-collections/community.general/blob/main/plugins/modules/ldap_search.py)

If these files are incorrect, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/devel/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
cc @eryx12o45 @jtyr
[click here for bot help](https://github.com/ansible/ansibullbot/blob/devel/ISSUE_HELP.md)
<!--- boilerplate: notify --->
After poking through the source code, it appears that subtree is indeed supported, but it's actually called "children" instead:

https://github.com/ansible-collections/community.general/blob/7dd7cbdba8b5ca422fbe826cad63392fe1f50ee7/plugins/modules/ldap_search.py#L211

A little confusing, to me at least, since in OpenLDAP for instance, the "children" scope is equivalent to "subordinate", not "subtree".

So perhaps a documentation issue - maybe the docs here should mention that "children" is actually "subtree": https://docs.ansible.com/ansible/latest/collections/community/general/ldap_search_module.html#parameter-scope
That's definitely a good idea. Do you want to create a PR to improve the documentation? You can find it here: https://github.com/ansible-collections/community.general/blob/main/plugins/modules/ldap_search.py#L46. (If you want to change it, add a new item in `description` - the items are paragraphs - and write something like `Note that V(children) ...`.)


Resolving patch:
diff --git a/plugins/modules/ldap_search.py b/plugins/modules/ldap_search.py
--- a/plugins/modules/ldap_search.py
+++ b/plugins/modules/ldap_search.py
@@ -44,6 +44,8 @@
     type: str
     description:
       - The LDAP scope to use.
+      - V(subordinate) requires the LDAPv3 subordinate feature extension.
+      - V(children) is equivalent to a "subtree" scope.
   filter:
     default: '(objectClass=*)'
     type: str


Test patch: