internet/ansible-freeipa
4
0
Fork 0
mirror of https://github.com/freeipa/ansible-freeipa.git synced 2026-03-26 21:33:05 +00:00
Code Issues Projects Releases Wiki Activity

New sysaccount management module

Browse Source 
There is a new sysaccount management module placed in the plugins folder:

    plugins/modules/ipasysaccount.py

The sysaccount module allows to ensure presence or absence of system
accounts.

Here is the documentation for the module:

    README-sysaccount.md

New sysaccount example playbooks:

    playbooks/sysaccount/sysaccount-absent.yml
    playbooks/sysaccount/sysaccount-disabled.yml
    playbooks/sysaccount/sysaccount-enabled.yml
    playbooks/sysaccount/sysaccount-present.yml
    playbooks/sysaccount/sysaccount-privileged.yml
    playbooks/sysaccount/sysaccount-unprivileged.yml

New tests for the module:

    tests/sysaccount/test_sysaccount.yml
    tests/sysaccount/test_sysaccount_client_context.yml
This commit is contained in:
Thomas Woerner
2025-11-05 14:36:19 +01:00
parent aa3bf1f015
commit dc9b0ce4e8
11 changed files with 763 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
README-sysaccount.md Normal file
View File

@@ -0,0 +1,196 @@
Sysaccount module
============
Description
-----------
The sysaccount module allows to ensure presence and absence of system accounts.
Features
--------
* Sysaccount management
Supported FreeIPA Versions
--------------------------
FreeIPA versions 4.4.0 and up are supported by the ipasysaccount module.
Requirements
------------
**Controller**
* Ansible version: 2.15+
**Node**
* Supported FreeIPA version (see above)
Usage
=====
Example inventory file
```ini
[ipaserver]
ipaserver.test.local
```
Example playbook to make sure sysaccount "my-app" is present with random password:
```yaml
---
- name: Playbook to manage IPA sysaccount.
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount "my-app" is present with random password
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
random: true
register: result
- name: Print generated random password
debug:
var: result.sysaccount.randompassword
```
Example playbook to make sure sysaccount "my-app" is present with given password:
```yaml
---
- name: Playbook to manage IPA sysaccount.
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount "my-app" is present with given password
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
password: SomeAPPpassword
```
Example playbook to make sure sysaccount "my-app" is absent:
```yaml
---
- name: Playbook to manage IPA sysaccount.
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount "my-app" is absent
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: absent
```
Example playbook to ensure existing sysaccount my-app is privileged
```yaml
---
- name: Playbook to manage IPA sysaccount.
hosts: ipaserver
become: false
tasks:
- name: Ensure existing sysaccount my-app is privileged
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
privileged: true
```
Example playbook to ensure existing sysaccount my-app is not privileged
```yaml
---
- name: Playbook to manage IPA sysaccount.
hosts: ipaserver
become: false
tasks:
- name: Ensure existing sysaccount my-app is not privileged
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
privileged: false
```
Example playbook to ensure existing sysaccount my-app is disabled
```yaml
---
- name: Playbook to manage IPA sysaccount.
hosts: ipaserver
become: false
tasks:
- name: Ensure existing sysaccount my-app is disabled
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: disabled
```
Example playbook to ensure existing sysaccount my-app is enabled
```yaml
---
- name: Playbook to manage IPA sysaccount.
hosts: ipaserver
become: false
tasks:
- name: Ensure existing sysaccount my-app is enabled
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: enabled
```
Variables
---------
Variable | Description | Required
-------- | ----------- | --------
`ipaadmin_principal` | The admin principal is a string and defaults to `admin` | no
`ipaadmin_password` | The admin password is a string and is required if there is no admin ticket available on the node | no
`ipaapi_context` | The context in which the module will execute. Executing in a server context is preferred. If not provided context will be determined by the execution environment. Valid values are `server` and `client`. | no
`ipaapi_ldap_cache` | Use LDAP cache for IPA connection. The bool setting defaults to true. (bool) | no
`name` \| `login` | The list of sysaccount name strings - internally uid. (list of strings) | yes
`description` | A description for the sysaccount. (string) | no
`privileged` | Allow password updates without reset. This flag is not replicated. It is needed to set privileged on all servers, where it is needed. (bool) | no
`random` | Generate a random user password. (bool) | no
`password` \| `userpassword` | Set the password. (string) | no
`update_password` | Set password for a sysaccount in present state only on creation or always. It can be one of `always` or `on_create` and defaults to `always`. | no
`state` | The state to ensure. It can be one of `present`, `absent`, 'enabled', 'disabled', default: `present`. | no
Return Values
=============
There are only return values if a random passwords has been generated.
Variable | Description | Returned When
-------- | ----------- | -------------
`sysaccount` | Sysaccount dict (dict) <br>Options: | Always
&nbsp; | `randompassword` - The generated random password | If random is yes and sysaccount did not exist or update_password is yes
Authors
=======
Thomas Woerner

2
README.md
View File

@@ -50,6 +50,7 @@ Features
* Modules for sudocmd management * Modules for sudocmd management
* Modules for sudocmdgroup management * Modules for sudocmdgroup management
* Modules for sudorule management * Modules for sudorule management
* Modules for sysaccount management
* Modules for topology management * Modules for topology management
* Modules for trust management * Modules for trust management
* Modules for user management * Modules for user management
@@ -465,6 +466,7 @@ Modules in plugin/modules
* [ipasudocmd](README-sudocmd.md) * [ipasudocmd](README-sudocmd.md)
* [ipasudocmdgroup](README-sudocmdgroup.md) * [ipasudocmdgroup](README-sudocmdgroup.md)
* [ipasudorule](README-sudorule.md) * [ipasudorule](README-sudorule.md)
* [ipasysaccount](README-sysaccount.md)
* [ipatopologysegment](README-topology.md) * [ipatopologysegment](README-topology.md)
* [ipatopologysuffix](README-topology.md) * [ipatopologysuffix](README-topology.md)
* [ipatrust](README-trust.md) * [ipatrust](README-trust.md)

11
playbooks/sysaccount/sysaccount-absent.yml Normal file
View File

@@ -0,0 +1,11 @@
---
- name: Sysaccount example
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount my-app is absent
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: absent

11
playbooks/sysaccount/sysaccount-disabled.yml Normal file
View File

@@ -0,0 +1,11 @@
---
- name: Sysaccount example
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount my-app is disabled
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: disabled

11
playbooks/sysaccount/sysaccount-enabled.yml Normal file
View File

@@ -0,0 +1,11 @@
---
- name: Sysaccount example
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount my-app is enabled
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: enabled

11
playbooks/sysaccount/sysaccount-present.yml Normal file
View File

@@ -0,0 +1,11 @@
---
- name: Sysaccount example
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount my-app is present with random password
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
random: true

11
playbooks/sysaccount/sysaccount-privileged.yml Normal file
View File

@@ -0,0 +1,11 @@
---
- name: Sysaccount example
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount my-app is privileged
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
privileged: true

11
playbooks/sysaccount/sysaccount-unprivileged.yml Normal file
View File

@@ -0,0 +1,11 @@
---
- name: Sysaccount example
hosts: ipaserver
become: false
tasks:
- name: Ensure sysaccount my-app is not privileged
ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
privileged: false

309
plugins/modules/ipasysaccount.py Normal file
View File

@@ -0,0 +1,309 @@
# -*- coding: utf-8 -*-
# Authors:
# Thomas Woerner <twoerner@redhat.com>
#
# Copyright (C) 2025 Red Hat
# see file 'COPYING' for use and warranty information
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
ANSIBLE_METADATA = {
"metadata_version": "1.0",
"supported_by": "community",
"status": ["preview"],
}
DOCUMENTATION = """
---
module: ipasysaccount
short_description: Manage FreeIPA system account
description: Manage FreeIPA system account
extends_documentation_fragment:
- ipamodule_base_docs
- ipamodule_base_docs.delete_continue
options:
name:
description: The list of sysaccount name strings (internally uid).
required: true
type: list
elements: str
aliases: ["login"]
description:
description: A description for the sysaccount.
type: str
required: false
privileged:
description: Allow password updates without reset.
type: bool
required: false
random:
description: Generate a random user password.
required: false
type: bool
password:
description: Set the user password.
required: false
type: str
aliases: ["userpassword"]
update_password:
description:
Set password for a sysaccount in present state only on creation or always
type: str
choices: ["always", "on_create"]
required: false
state:
description: The state to ensure.
choices: ["present", "absent", "enabled", "disabled"]
default: present
type: str
author:
- Thomas Woerner (@t-woerner)
"""
EXAMPLES = """
# Ensure sysaccount my-app is present
- ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
random: true
# Ensure sysaccount my-app is absent
- ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: absent
# Ensure existing sysaccount my-app is privileged
- ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
privileged: true
# Ensure existing sysaccount my-app is not privileged
- ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
privileged: false
# Ensure existing sysaccount my-app is disabled
- ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: disabled
# Ensure existing sysaccount my-app is enabled
- ipasysaccount:
ipaadmin_password: SomeADMINpassword
name: my-app
state: enabled
"""
RETURN = """
sysaccount:
description: Sysaccount dict with random password
returned: |
If random is yes and user sysaccount not exist or update_password is yes
type: dict
contains:
randompassword:
description: The generated random password
type: str
"""
from ansible.module_utils.ansible_freeipa_module import \
IPAAnsibleModule, compare_args_ipa, ipalib_errors
from ansible.module_utils import six
if six.PY3:
unicode = str
def find_sysaccount(module, name):
"""Find if a sysaccount with the given name already exist."""
try:
_result = module.ipa_command("sysaccount_show", name, {"all": True})
except ipalib_errors.NotFound:
# An exception is raised if sysaccount name is not found.
return None
return _result["result"]
def gen_args(description, random, privileged, password):
_args = {}
if description is not None:
_args["description"] = description
if random is not None:
_args["random"] = random
if privileged is not None:
_args["privileged"] = privileged
if password is not None:
_args["userpassword"] = password
return _args
# pylint: disable=unused-argument
def result_handler(module, result, command, name, args, exit_args, errors):
if "random" in args and command in ["sysaccount_add", "sysaccount_mod"] \
and "randompassword" in result["result"]:
exit_args["randompassword"] = \
result["result"]["randompassword"]
def main():
ansible_module = IPAAnsibleModule(
argument_spec=dict(
# general
name=dict(type="list", elements="str", required=True,
aliases=["login"]),
# present
description=dict(required=False, type='str', default=None),
random=dict(required=False, type='bool', default=None),
privileged=dict(required=False, type='bool', default=None),
password=dict(required=False, type='str',
aliases=["userpassword"], default=None),
# mod
update_password=dict(type='str', default=None, no_log=False,
choices=['always', 'on_create']),
# state
state=dict(type="str", default="present",
choices=["present", "absent", "enabled", "disabled"]),
),
supports_check_mode=True,
ipa_module_options=["delete_continue"],
mutually_exclusive=[["random", "password"]]
)
ansible_module._ansible_debug = True
# Get parameters
# general
names = ansible_module.params_get("name")
# present
description = ansible_module.params_get("description")
random = ansible_module.params_get("random")
privileged = ansible_module.params_get("privileged")
password = ansible_module.params_get("password")
# mod
update_password = ansible_module.params_get("update_password")
# absent
delete_continue = ansible_module.params_get("delete_continue")
# state
state = ansible_module.params_get("state")
# Check parameters
invalid = []
if state == "present" and len(names) != 1:
ansible_module.fail_json(
msg="Only one sysaccount can be added at a time.")
if state in ["absent", "enabled", "disabled"]:
if len(names) < 1:
ansible_module.fail_json(msg="No name given.")
invalid = ["description", "random", "privileged", "password"]
ansible_module.params_fail_used_invalid(invalid, state)
# Init
changed = False
exit_args = {}
# Connect to IPA API
with ansible_module.ipa_connect():
if not ansible_module.ipa_command_exists("sysaccount_add"):
ansible_module.fail_json(
msg=("Managing sysaccounts is not supported by your "
"IPA version")
)
commands = []
for name in names:
# Make sure sysaccount exists
res_find = find_sysaccount(ansible_module, name)
# Create command
if state == "present":
# Generate args
args = gen_args(description, random, privileged, password)
# Found the sysaccount
if res_find is not None:
# Ignore password and random with
# update_password == on_create
if update_password == "on_create":
if "userpassword" in args:
del args["userpassword"]
if "random" in args:
del args["random"]
# if using "random:false" password should not be
# generated.
if not args.get("random", True):
del args["random"]
# For all settings is args, check if there are
# different settings in the find result.
# If yes: modify
if not compare_args_ipa(ansible_module, args,
res_find):
commands.append([name, "sysaccount_mod", args])
else:
commands.append([name, "sysaccount_add", args])
elif state == "absent":
if res_find is not None:
commands.append(
[name, "sysaccount_del", {"continue": delete_continue}]
)
elif state == "enabled":
if res_find is not None and res_find["nsaccountlock"]:
commands.append([name, "sysaccount_enable", {}])
elif state == "disabled":
if res_find is not None and not res_find["nsaccountlock"]:
commands.append([name, "sysaccount_disable", {}])
else:
ansible_module.fail_json(msg="Unkown state '%s'" % state)
# Execute commands
changed = ansible_module.execute_ipa_commands(
commands, result_handler, keeponly=["randompassword"],
exit_args=exit_args)
# Done
ansible_module.exit_json(changed=changed, sysaccount=exit_args)
if __name__ == "__main__":
main()

150
tests/sysaccount/test_sysaccount.yml Normal file
View File

@@ -0,0 +1,150 @@
---
- name: Test sysaccount
hosts: "{{ ipa_test_host | default('ipaserver') }}"
# It is normally not needed to set "become" to "true" for a module test.
# Only set it to true if it is needed to execute commands as root.
become: false
# Enable "gather_facts" only if "ansible_facts" variable needs to be used.
gather_facts: false
module_defaults:
ipasysaccount:
ipaadmin_password: SomeADMINpassword
ipaapi_context: "{{ ipa_context | default(omit) }}"
tasks:
- name: Verify sysaccount tests are possible
ansible.builtin.shell:
cmd: |
echo SomeADMINpassword | kinit -c {{ krb5ccname }} admin > /dev/null
RESULT=$(KRB5CCNAME={{ krb5ccname }} ipa sysaccount-add --help)
kdestroy -A -c {{ krb5ccname }} > /dev/null
echo $RESULT
vars:
krb5ccname: "__check_ipa_sysaccount_add__"
register: check_sysaccount_add
- name: Execute tests
when: '"ipa: ERROR: unknown command" not in check_sysaccount_add.stderr'
block:
# CLEANUP TEST ITEMS
- name: Ensure sysaccount my-app is absent
ipasysaccount:
name: my-app
state: absent
# CREATE TEST ITEMS
# TESTS
- name: Ensure sysaccount my-app is present with random password
ipasysaccount:
name: my-app
random: true
register: result
failed_when: not result.changed or
result.sysaccount.randompassword is not defined or
result.failed
- name: Ensure sysaccount my-app is present, again with updated random password and update_password always
ipasysaccount:
name: my-app
random: true
register: result2
failed_when: not result2.changed or
result2.sysaccount.randompassword is not defined or
result2.sysaccount.randompassword == result.sysaccount.randompassword or
result2.failed
- name: Ensure sysaccount my-app is present, again with random password and update_password on_create
ipasysaccount:
name: my-app
random: true
update_password: on_create
register: result
failed_when: not result2.changed or
result.sysaccount.randompassword is defined or
result.failed
# more tests here
- name: Ensure sysaccount my-app is disabled
ipasysaccount:
name: my-app
state: disabled
register: result
failed_when: not result.changed or result.failed
- name: Ensure sysaccount my-app is disabled, again
ipasysaccount:
name: my-app
state: disabled
register: result
failed_when: result.changed or result.failed
- name: Ensure sysaccount my-app is enabled
ipasysaccount:
name: my-app
state: enabled
register: result
failed_when: not result.changed or result.failed
- name: Ensure sysaccount my-app is enabled, again
ipasysaccount:
name: my-app
state: enabled
register: result
failed_when: result.changed or result.failed
- name: Ensure sysaccount my-app is privileged
ipasysaccount:
name: my-app
privileged: true
register: result
failed_when: not result.changed or result.failed
- name: Ensure sysaccount my-app is privileged, again
ipasysaccount:
name: my-app
privileged: true
register: result
failed_when: result.changed or result.failed
# ADDITIONAL TEST HERE?
- name: Ensure sysaccount my-app is not privileged
ipasysaccount:
name: my-app
privileged: false
register: result
failed_when: not result.changed or result.failed
- name: Ensure sysaccount my-app is not privileged, again
ipasysaccount:
name: my-app
privileged: false
register: result
failed_when: result.changed or result.failed
- name: Ensure sysaccount my-app is absent
ipasysaccount:
name: my-app
state: absent
register: result
failed_when: not result.changed or result.failed
- name: Ensure sysaccount my-app is absent again
ipasysaccount:
name: my-app
state: absent
register: result
failed_when: result.changed or result.failed
# CLEANUP TEST ITEMS
- name: Ensure sysaccount my-app is absent
ipasysaccount:
name: my-app
state: absent

40
tests/sysaccount/test_sysaccount_client_context.yml Normal file
View File

@@ -0,0 +1,40 @@
---
- name: Test sysaccount
hosts: ipaclients, ipaserver
# It is normally not needed to set "become" to "true" for a module test.
# Only set it to true if it is needed to execute commands as root.
become: false
# Enable "gather_facts" only if "ansible_facts" variable needs to be used.
gather_facts: false
tasks:
- name: Include FreeIPA facts.
ansible.builtin.include_tasks: ../env_freeipa_facts.yml
# Test will only be executed if host is not a server.
- name: Execute with server context in the client.
ipasysaccount:
ipaadmin_password: SomeADMINpassword
ipaapi_context: server
name: ThisShouldNotWork
register: result
failed_when: not (result.failed and result.msg is regex("No module named '*ipaserver'*"))
when: ipa_host_is_client
# Import basic module tests, and execute with ipa_context set to 'client'.
# If ipaclients is set, it will be executed using the client, if not,
# ipaserver will be used.
#
# With this setup, tests can be executed against an IPA client, against
# an IPA server using "client" context, and ensure that tests are executed
# in upstream CI.
- name: Test sysaccount using client context, in client host.
import_playbook: test_sysaccount.yml
when: groups['ipaclients']
vars:
ipa_test_host: ipaclients
- name: Test sysaccount using client context, in server host.
import_playbook: test_sysaccount.yml
when: groups['ipaclients'] is not defined or not groups['ipaclients']