Some attribute values are only accepted for specific FreeIPA versions,
for example `self` for permission's `bindtype`. Although there are
options to check for command and parameter availability, there is no
check for verifying if a value should be accepted.

This patch add a function to evaluate the target FreeIPA host version,
by comparing a giver version to the current installed one.

The version evaluation uses Python packaging's version comparision,
which is compatible with PEP 440, if available. If not available, it
falls back to a string split, that will work for the most common cases,
but might fail for versions including strings with `rc` or `dev`, for
example.

Bypass Ansible filtering on data returned by the module.

Fix utils/changelog for merge commits without subject

Due to Ansible filtering out values in the output that might be match
values in sensible attributes that have `no_log` set, if a module need
to return data to the controller, it cannot rely on
`ansible_module.exit_json` if there is a chance that a partial match
may occur.

See: https://github.com/ansible/ansible/issues/71789

The change provided here uses the same implementation that is used on
Ansible's `AnsibleModule.exit_json`, without the data filtering layer,
so every attribute with be printed and, therefore, logged by Ansible.

This is needed for the Vault module, as we need to return values that
are explicit requested by the user and that might, at least partially,
match the values in attributes with `no_log` set.

Tests that reproduced the issue, and show it was fixed were provided
for all Vault types.

Add support for adding external members to ipagroup.

build-galaxy-release: Galaxyfy READMEs, module EXAMPLES and tests

Up to now the snippets in the README files, the EXAMPLES in the modules
and also the tests playbooks have not been adapted while building the
collection.

These are the invoved python files:

    utils/galaxyfy-README.py
    utils/galaxyfy-module-EXAMPLES.py
    utils/galaxyfy-playbook.py
    utils/galaxyfy.py

utils/galaxyfy.py provides the function galaxyfy_playbook, which has been
extended and is used in galaxyfy-playbook.py, galaxyfy-README.py and
galaxyfy-module-EXAMPLES.py.

There is curently a merge commit without a subject, which leads into a
traceback in the changelog script.

The merge information provides the commit hash, which is now used to get
the subject later on using the generated commits hash.

New backup role

There is a new backup role in the roles folder:

    roles/ipabackup

This role allows to backup an IPA server, to copy a backup from the
server to the controller, to copy all backups from the server to the
controller, to remove a backup from the server, to remove all backups
from the server, to restore an IPA server locally and from the controller
and also to copy a backup from the controller to the server.

Here is the documentation for the role:

    roles/ipabackup/README.md

New example playbooks have been added:

    playbooks/backup-server.yml
    playbooks/backup-server-to-controller.yml
    playbooks/copy-backup-from-server.yml
    playbooks/copy-all-backups-from-server.yml
    playbooks/remove-backup-from-server.yml
    playbooks/remove-all-backups-from-server.yml
    playbooks/copy-backup-to-server.yml
    playbooks/restore-server-from-controller.yml
    playbooks/restore-server.yml

Add note about `no_log` use on vault data retrieve.

When using the ipavault module to retrieve stored data, this data is
often sensitive, and if `no_log` is not enabled on the playbook, the
sensitive data will be logged by Ansible.

This change in de documentation, and playbook examples, suggests the
use of `no_log: true` when using `state: retrieved` with ipavault.

Fix symmetric vault password change when using password_files.

There is a new permission management module placed in the plugins folder:

    plugins/modules/ipapermission.py

The permission module allows to ensure presence of absence of permissions
and manage permission members.

Here is the documentation for the module:

    README-permission.md

New example plabooks have been added:

    playbooks/permission/permission-absent.yml
    playbooks/permission/permission-allow-read-employeenum.yml
    playbooks/permission/permission-member-absent.yml
    playbooks/permission/permission-member-present.yml
    playbooks/permission/permission-present.yml
    playbooks/permission/permission-renamed.yml

New tests for the module:

    tests/permission/test_permission.yml

This patch add support for adding external members to ipagroup which
have the `external` attribute set. It adds another attribute to the
module, `external_members`, which is a list of users or groups from
an external trust, to be added to the group.

This patch requires server-trust-ad to be tested, as such, the tests
have been guarded by a test block, for when such tests are available
in ansible-freeipa CI.

Fixes issue #418

New script utils/changelog

New script utils/ansible-doc-test

This scrip can be used to generate the changelog text for a new
ansible-freeipa release on github.

    usage: Usage: changelog [options] [<new version>]

    optional arguments:
      -h, --help  show this help message and exit
      --tag TAG   git tag

If the script is used without a givn tag, it will show all the changes since
the last tag. If a tag (this can be a also a commit) is given, then all
changes since this commit are shown.

This script can check modules in roles and also plugins folder to have
a valid documentation section. It is using anisble-doc internally.

    usage: Usage: ansible-doc-test [options] [path]

    optional arguments:
      -h, --help  show this help message and exit
      -v          increase output verbosity

There are different verbose levels:

    -v   Shows the modules that are tested at the moment.
    -vv  Shows the modules and also the doc output.

You can use the script to check specific modules, roles or modules in roles.
Here are some examples:

Test specific module with verbose level 1:
    $ utils/ansible-doc-test -vv plugins/modules/ipauser.py

Test all modules in plugins folder:
    $ utils/ansible-doc-test -v plugins

Test ipaserver_prepare.py in ipaserver role:
    $ utils/ansible-doc-test -v roles/ipaserver/library/ipaserver_prepare.py

Test all modules in ipaserver role:
    $ utils/ansible-doc-test -v roles/ipaserver

Test all roles:
    $ utils/ansible-doc-test -v roles

Test all roles and modules in plugins:
    $ utils/ansible-doc-test -v

Fix module documentation

ansible-doc is reporting several issues in modules. Most of them have benn
due to misspelled description key word or due to use of multi line text
without the | in the description line.

ipa[server,replica,client]: Fix moved sysrestore and is_ipa_configured

https://pagure.io/freeipa/issue/8458 moved more things to the ipalib and
ipalib.facts:

- sysrestore has been moved from ipalib.install to ipalib
- is_ipa_configured has been moved from ipaserver.install.installutils to
  ipalib.facts

Fixes: #394 (TASK [ipaclient : Install - IPA client test] Error: module
                  'ipalib.install.sysrestore' has no attribute
                  'SYSRESTORE_STATEFILE')

When using changing passwords, using password files, the file name was
being used as the password, and not its content. This patch fixes the
behavior to use the contents of the password file.

Tests have been added to ensure the correct behavior.

ipa[server,replica,client]: Drop deactivated Python2/3 test

ipa[server,replica]: New variables to set firewalld zone

These tests have been deactivated for some time with b51397eb and are
removed now.

The new variables ipa[server,replica]_firewalld_zone have been added to
be able to set the zone in which the needed services for IPA are enabled.

New tasks have been added to check if the zone is available in the runtime
and also permamanet environment.

The code to enable firewalld has been moved out of thee
ipa[server,replica]_install_packages blocks to make sure that the firewalld
service is also enabled if the package is already installed.

Fixes: issue #177 (How to set up firewalld zones?)

Added helpers to config tests for execution on idm-ci

Fixed log of vault data return when retrieving to a file.

When retrieving data from a vault using `out` to store the data in a
file resulted is random characters being returned and logged. These
characters could generate a traceback print from Ansible's logger,
without breaking the script.

The reason for that is that the result from `vault_retrive` was being
processed when it was not needed, and data was beeing returned, when
it shouldn't.

This patch fixes this behavior by supressing the return data when `data`
is not available, and only raising an error if it should be available.

ipaserver/module_utils/ansible_ipa_server: IPA_MODULES moved to ipalib.facts

New privilege management module

There is a new privilege management module placed in the plugins folder:

    plugins/modules/ipaprivilege.py

The privilege module allows to ensure presence or absence of privilege
and manage privilege permission memebers.

Here is the documentation for the module:

    README-privilege.md

New example playbooks have been added:

    playbooks/privilege/privilege-absent.yml
    playbooks/privilege/privilege-member-absent.yml
    playbooks/privilege/privilege-member-present.yml
    playbooks/privilege/privilege-present.yml

New tests for the module:

    tests/privilege/test_privilege.yml

tests/user/test_users_present_slice.yml: Fix missing users.json

users.json is generated for the tests and not part of the repo any more.
This test was lacking the include to generate the file.

Related to: b7e1a99b
            tests/user/test_users*.yml: Use extended dynamic users.json

added trust module and docs

IPA_MODULES has been moved from ipaserver.install.installutils to
ipalib.facts with https://pagure.io/freeipa/issue/8458