From 29e32267186ba15fd0a2b8799542b82d52061e2c Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Mon, 30 Dec 2024 08:23:59 +1300 Subject: [PATCH] normalize docs in become plugins (#9452) * normalize docs in become plugins Normalize doc blocks for plugins * adjustments --- plugins/become/doas.py | 158 ++++++++++++++++----------------- plugins/become/dzdo.py | 132 ++++++++++++++-------------- plugins/become/ksu.py | 160 +++++++++++++++++----------------- plugins/become/machinectl.py | 151 ++++++++++++++++---------------- plugins/become/pbrun.py | 156 ++++++++++++++++----------------- plugins/become/pfexec.py | 164 +++++++++++++++++------------------ plugins/become/pmrun.py | 108 +++++++++++------------ plugins/become/run0.py | 114 ++++++++++++------------ plugins/become/sesu.py | 134 ++++++++++++++-------------- plugins/become/sudosu.py | 135 ++++++++++++++-------------- 10 files changed, 706 insertions(+), 706 deletions(-) diff --git a/plugins/become/doas.py b/plugins/become/doas.py index 9d3a73b5b0..9011fa69e9 100644 --- a/plugins/become/doas.py +++ b/plugins/become/doas.py @@ -5,86 +5,86 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: doas - short_description: Do As user +DOCUMENTATION = r""" +name: doas +short_description: Do As user +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(doas) utility. +author: Ansible Core Team +options: + become_user: + description: User you 'become' to execute the task. + type: string + ini: + - section: privilege_escalation + key: become_user + - section: doas_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_doas_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_DOAS_USER + become_exe: + description: C(doas) executable. + type: string + default: doas + ini: + - section: privilege_escalation + key: become_exe + - section: doas_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_doas_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_DOAS_EXE + become_flags: + description: Options to pass to C(doas). + type: string + default: '' + ini: + - section: privilege_escalation + key: become_flags + - section: doas_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_doas_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_DOAS_FLAGS + become_pass: + description: Password for C(doas) prompt. + type: string + required: false + vars: + - name: ansible_become_password + - name: ansible_become_pass + - name: ansible_doas_pass + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_DOAS_PASS + ini: + - section: doas_become_plugin + key: password + prompt_l10n: description: - - This become plugins allows your remote/login user to execute commands as another user via the doas utility. - author: Ansible Core Team - options: - become_user: - description: User you 'become' to execute the task. - type: string - ini: - - section: privilege_escalation - key: become_user - - section: doas_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_doas_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_DOAS_USER - become_exe: - description: Doas executable. - type: string - default: doas - ini: - - section: privilege_escalation - key: become_exe - - section: doas_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_doas_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_DOAS_EXE - become_flags: - description: Options to pass to doas. - type: string - default: '' - ini: - - section: privilege_escalation - key: become_flags - - section: doas_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_doas_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_DOAS_FLAGS - become_pass: - description: Password for doas prompt. - type: string - required: false - vars: - - name: ansible_become_password - - name: ansible_become_pass - - name: ansible_doas_pass - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_DOAS_PASS - ini: - - section: doas_become_plugin - key: password - prompt_l10n: - description: - - List of localized strings to match for prompt detection. - - If empty we will use the built in one. - type: list - elements: string - default: [] - ini: - - section: doas_become_plugin - key: localized_prompts - vars: - - name: ansible_doas_prompt_l10n - env: - - name: ANSIBLE_DOAS_PROMPT_L10N -''' + - List of localized strings to match for prompt detection. + - If empty we will use the built in one. + type: list + elements: string + default: [] + ini: + - section: doas_become_plugin + key: localized_prompts + vars: + - name: ansible_doas_prompt_l10n + env: + - name: ANSIBLE_DOAS_PROMPT_L10N +""" import re diff --git a/plugins/become/dzdo.py b/plugins/become/dzdo.py index 323d1b7395..70e2e0d777 100644 --- a/plugins/become/dzdo.py +++ b/plugins/become/dzdo.py @@ -5,72 +5,72 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: dzdo - short_description: Centrify's Direct Authorize - description: - - This become plugins allows your remote/login user to execute commands as another user via the dzdo utility. - author: Ansible Core Team - options: - become_user: - description: User you 'become' to execute the task. - type: string - ini: - - section: privilege_escalation - key: become_user - - section: dzdo_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_dzdo_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_DZDO_USER - become_exe: - description: Dzdo executable. - type: string - default: dzdo - ini: - - section: privilege_escalation - key: become_exe - - section: dzdo_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_dzdo_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_DZDO_EXE - become_flags: - description: Options to pass to dzdo. - type: string - default: -H -S -n - ini: - - section: privilege_escalation - key: become_flags - - section: dzdo_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_dzdo_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_DZDO_FLAGS - become_pass: - description: Options to pass to dzdo. - type: string - required: false - vars: - - name: ansible_become_password - - name: ansible_become_pass - - name: ansible_dzdo_pass - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_DZDO_PASS - ini: - - section: dzdo_become_plugin - key: password -''' +DOCUMENTATION = r""" +name: dzdo +short_description: Centrify's Direct Authorize +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(dzdo) utility. +author: Ansible Core Team +options: + become_user: + description: User you 'become' to execute the task. + type: string + ini: + - section: privilege_escalation + key: become_user + - section: dzdo_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_dzdo_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_DZDO_USER + become_exe: + description: C(dzdo) executable. + type: string + default: dzdo + ini: + - section: privilege_escalation + key: become_exe + - section: dzdo_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_dzdo_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_DZDO_EXE + become_flags: + description: Options to pass to C(dzdo). + type: string + default: -H -S -n + ini: + - section: privilege_escalation + key: become_flags + - section: dzdo_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_dzdo_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_DZDO_FLAGS + become_pass: + description: Options to pass to C(dzdo). + type: string + required: false + vars: + - name: ansible_become_password + - name: ansible_become_pass + - name: ansible_dzdo_pass + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_DZDO_PASS + ini: + - section: dzdo_become_plugin + key: password +""" from ansible.plugins.become import BecomeBase diff --git a/plugins/become/ksu.py b/plugins/become/ksu.py index 8ee8f89512..88a29e7362 100644 --- a/plugins/become/ksu.py +++ b/plugins/become/ksu.py @@ -5,87 +5,87 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: ksu - short_description: Kerberos substitute user +DOCUMENTATION = r""" +name: ksu +short_description: Kerberos substitute user +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(ksu) utility. +author: Ansible Core Team +options: + become_user: + description: User you 'become' to execute the task. + type: string + ini: + - section: privilege_escalation + key: become_user + - section: ksu_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_ksu_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_KSU_USER + required: true + become_exe: + description: C(ksu) executable. + type: string + default: ksu + ini: + - section: privilege_escalation + key: become_exe + - section: ksu_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_ksu_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_KSU_EXE + become_flags: + description: Options to pass to C(ksu). + type: string + default: '' + ini: + - section: privilege_escalation + key: become_flags + - section: ksu_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_ksu_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_KSU_FLAGS + become_pass: + description: C(ksu) password. + type: string + required: false + vars: + - name: ansible_ksu_pass + - name: ansible_become_pass + - name: ansible_become_password + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_KSU_PASS + ini: + - section: ksu_become_plugin + key: password + prompt_l10n: description: - - This become plugins allows your remote/login user to execute commands as another user via the ksu utility. - author: Ansible Core Team - options: - become_user: - description: User you 'become' to execute the task. - type: string - ini: - - section: privilege_escalation - key: become_user - - section: ksu_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_ksu_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_KSU_USER - required: true - become_exe: - description: Su executable. - type: string - default: ksu - ini: - - section: privilege_escalation - key: become_exe - - section: ksu_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_ksu_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_KSU_EXE - become_flags: - description: Options to pass to ksu. - type: string - default: '' - ini: - - section: privilege_escalation - key: become_flags - - section: ksu_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_ksu_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_KSU_FLAGS - become_pass: - description: Ksu password. - type: string - required: false - vars: - - name: ansible_ksu_pass - - name: ansible_become_pass - - name: ansible_become_password - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_KSU_PASS - ini: - - section: ksu_become_plugin - key: password - prompt_l10n: - description: - - List of localized strings to match for prompt detection. - - If empty we will use the built in one. - type: list - elements: string - default: [] - ini: - - section: ksu_become_plugin - key: localized_prompts - vars: - - name: ansible_ksu_prompt_l10n - env: - - name: ANSIBLE_KSU_PROMPT_L10N -''' + - List of localized strings to match for prompt detection. + - If empty we will use the built in one. + type: list + elements: string + default: [] + ini: + - section: ksu_become_plugin + key: localized_prompts + vars: + - name: ansible_ksu_prompt_l10n + env: + - name: ANSIBLE_KSU_PROMPT_L10N +""" import re diff --git a/plugins/become/machinectl.py b/plugins/become/machinectl.py index 1dd648e6e0..1dd80bc80f 100644 --- a/plugins/become/machinectl.py +++ b/plugins/become/machinectl.py @@ -5,91 +5,90 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: machinectl - short_description: Systemd's machinectl privilege escalation - description: - - This become plugins allows your remote/login user to execute commands as another user via the machinectl utility. - author: Ansible Core Team - options: - become_user: - description: User you 'become' to execute the task. - type: string - default: '' - ini: - - section: privilege_escalation - key: become_user - - section: machinectl_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_machinectl_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_MACHINECTL_USER - become_exe: - description: Machinectl executable. - type: string - default: machinectl - ini: - - section: privilege_escalation - key: become_exe - - section: machinectl_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_machinectl_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_MACHINECTL_EXE - become_flags: - description: Options to pass to machinectl. - type: string - default: '' - ini: - - section: privilege_escalation - key: become_flags - - section: machinectl_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_machinectl_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_MACHINECTL_FLAGS - become_pass: - description: Password for machinectl. - type: string - required: false - vars: - - name: ansible_become_password - - name: ansible_become_pass - - name: ansible_machinectl_pass - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_MACHINECTL_PASS - ini: - - section: machinectl_become_plugin - key: password - notes: - - When not using this plugin with user V(root), it only works correctly with a polkit rule which will alter - the behaviour of machinectl. This rule must alter the prompt behaviour to ask directly for the user credentials, - if the user is allowed to perform the action (take a look at the examples section). - If such a rule is not present the plugin only work if it is used in context with the root user, - because then no further prompt will be shown by machinectl. -''' +DOCUMENTATION = r""" +name: machinectl +short_description: Systemd's machinectl privilege escalation +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(machinectl) utility. +author: Ansible Core Team +options: + become_user: + description: User you 'become' to execute the task. + type: string + default: '' + ini: + - section: privilege_escalation + key: become_user + - section: machinectl_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_machinectl_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_MACHINECTL_USER + become_exe: + description: C(machinectl) executable. + type: string + default: machinectl + ini: + - section: privilege_escalation + key: become_exe + - section: machinectl_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_machinectl_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_MACHINECTL_EXE + become_flags: + description: Options to pass to C(machinectl). + type: string + default: '' + ini: + - section: privilege_escalation + key: become_flags + - section: machinectl_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_machinectl_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_MACHINECTL_FLAGS + become_pass: + description: Password for C(machinectl). + type: string + required: false + vars: + - name: ansible_become_password + - name: ansible_become_pass + - name: ansible_machinectl_pass + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_MACHINECTL_PASS + ini: + - section: machinectl_become_plugin + key: password +notes: + - When not using this plugin with user V(root), it only works correctly with a polkit rule which will alter the behaviour + of machinectl. This rule must alter the prompt behaviour to ask directly for the user credentials, if the user is allowed + to perform the action (take a look at the examples section). If such a rule is not present the plugin only work if it + is used in context with the root user, because then no further prompt will be shown by machinectl. +""" -EXAMPLES = r''' +EXAMPLES = r""" # A polkit rule needed to use the module with a non-root user. # See the Notes section for details. -/etc/polkit-1/rules.d/60-machinectl-fast-user-auth.rules: | +/etc/polkit-1/rules.d/60-machinectl-fast-user-auth.rules: |- polkit.addRule(function(action, subject) { if(action.id == "org.freedesktop.machine1.host-shell" && subject.isInGroup("wheel")) { return polkit.Result.AUTH_SELF_KEEP; } }); -''' +""" from re import compile as re_compile diff --git a/plugins/become/pbrun.py b/plugins/become/pbrun.py index ccba615a85..56f3b2c315 100644 --- a/plugins/become/pbrun.py +++ b/plugins/become/pbrun.py @@ -5,84 +5,84 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: pbrun - short_description: PowerBroker run - description: - - This become plugins allows your remote/login user to execute commands as another user via the pbrun utility. - author: Ansible Core Team - options: - become_user: - description: User you 'become' to execute the task. - type: string - default: '' - ini: - - section: privilege_escalation - key: become_user - - section: pbrun_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_pbrun_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_PBRUN_USER - become_exe: - description: Sudo executable. - type: string - default: pbrun - ini: - - section: privilege_escalation - key: become_exe - - section: pbrun_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_pbrun_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_PBRUN_EXE - become_flags: - description: Options to pass to pbrun. - type: string - default: '' - ini: - - section: privilege_escalation - key: become_flags - - section: pbrun_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_pbrun_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_PBRUN_FLAGS - become_pass: - description: Password for pbrun. - type: string - required: false - vars: - - name: ansible_become_password - - name: ansible_become_pass - - name: ansible_pbrun_pass - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_PBRUN_PASS - ini: - - section: pbrun_become_plugin - key: password - wrap_exe: - description: Toggle to wrap the command pbrun calls in C(shell -c) or not. - default: false - type: bool - ini: - - section: pbrun_become_plugin - key: wrap_execution - vars: - - name: ansible_pbrun_wrap_execution - env: - - name: ANSIBLE_PBRUN_WRAP_EXECUTION -''' +DOCUMENTATION = r""" +name: pbrun +short_description: PowerBroker run +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(pbrun) utility. +author: Ansible Core Team +options: + become_user: + description: User you 'become' to execute the task. + type: string + default: '' + ini: + - section: privilege_escalation + key: become_user + - section: pbrun_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_pbrun_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_PBRUN_USER + become_exe: + description: C(pbrun) executable. + type: string + default: pbrun + ini: + - section: privilege_escalation + key: become_exe + - section: pbrun_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_pbrun_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_PBRUN_EXE + become_flags: + description: Options to pass to C(pbrun). + type: string + default: '' + ini: + - section: privilege_escalation + key: become_flags + - section: pbrun_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_pbrun_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_PBRUN_FLAGS + become_pass: + description: Password for C(pbrun). + type: string + required: false + vars: + - name: ansible_become_password + - name: ansible_become_pass + - name: ansible_pbrun_pass + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_PBRUN_PASS + ini: + - section: pbrun_become_plugin + key: password + wrap_exe: + description: Toggle to wrap the command C(pbrun) calls in C(shell -c) or not. + default: false + type: bool + ini: + - section: pbrun_become_plugin + key: wrap_execution + vars: + - name: ansible_pbrun_wrap_execution + env: + - name: ANSIBLE_PBRUN_WRAP_EXECUTION +""" from ansible.plugins.become import BecomeBase diff --git a/plugins/become/pfexec.py b/plugins/become/pfexec.py index 8794b6173c..62d22bdb61 100644 --- a/plugins/become/pfexec.py +++ b/plugins/become/pfexec.py @@ -5,89 +5,89 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: pfexec - short_description: profile based execution +DOCUMENTATION = r""" +name: pfexec +short_description: profile based execution +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(pfexec) utility. +author: Ansible Core Team +options: + become_user: description: - - This become plugins allows your remote/login user to execute commands as another user via the pfexec utility. - author: Ansible Core Team - options: - become_user: - description: - - User you 'become' to execute the task. - - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, - but it is supplied here for Ansible to make decisions needed for the task execution, like file permissions. - type: string - default: root - ini: - - section: privilege_escalation - key: become_user - - section: pfexec_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_pfexec_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_PFEXEC_USER - become_exe: - description: Sudo executable. - type: string - default: pfexec - ini: - - section: privilege_escalation - key: become_exe - - section: pfexec_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_pfexec_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_PFEXEC_EXE - become_flags: - description: Options to pass to pfexec. - type: string - default: -H -S -n - ini: - - section: privilege_escalation - key: become_flags - - section: pfexec_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_pfexec_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_PFEXEC_FLAGS - become_pass: - description: pfexec password. - type: string - required: false - vars: - - name: ansible_become_password - - name: ansible_become_pass - - name: ansible_pfexec_pass - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_PFEXEC_PASS - ini: - - section: pfexec_become_plugin - key: password - wrap_exe: - description: Toggle to wrap the command pfexec calls in C(shell -c) or not. - default: false - type: bool - ini: - - section: pfexec_become_plugin - key: wrap_execution - vars: - - name: ansible_pfexec_wrap_execution - env: - - name: ANSIBLE_PFEXEC_WRAP_EXECUTION - notes: - - This plugin ignores O(become_user) as pfexec uses its own C(exec_attr) to figure this out. -''' + - User you 'become' to execute the task. + - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here + for Ansible to make decisions needed for the task execution, like file permissions. + type: string + default: root + ini: + - section: privilege_escalation + key: become_user + - section: pfexec_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_pfexec_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_PFEXEC_USER + become_exe: + description: C(pfexec) executable. + type: string + default: pfexec + ini: + - section: privilege_escalation + key: become_exe + - section: pfexec_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_pfexec_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_PFEXEC_EXE + become_flags: + description: Options to pass to C(pfexec). + type: string + default: -H -S -n + ini: + - section: privilege_escalation + key: become_flags + - section: pfexec_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_pfexec_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_PFEXEC_FLAGS + become_pass: + description: C(pfexec) password. + type: string + required: false + vars: + - name: ansible_become_password + - name: ansible_become_pass + - name: ansible_pfexec_pass + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_PFEXEC_PASS + ini: + - section: pfexec_become_plugin + key: password + wrap_exe: + description: Toggle to wrap the command C(pfexec) calls in C(shell -c) or not. + default: false + type: bool + ini: + - section: pfexec_become_plugin + key: wrap_execution + vars: + - name: ansible_pfexec_wrap_execution + env: + - name: ANSIBLE_PFEXEC_WRAP_EXECUTION +notes: + - This plugin ignores O(become_user) as pfexec uses its own C(exec_attr) to figure this out. +""" from ansible.plugins.become import BecomeBase diff --git a/plugins/become/pmrun.py b/plugins/become/pmrun.py index 093906214d..64820ecde5 100644 --- a/plugins/become/pmrun.py +++ b/plugins/become/pmrun.py @@ -5,60 +5,60 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: pmrun - short_description: Privilege Manager run - description: - - This become plugins allows your remote/login user to execute commands as another user via the pmrun utility. - author: Ansible Core Team - options: - become_exe: - description: Sudo executable - type: string - default: pmrun - ini: - - section: privilege_escalation - key: become_exe - - section: pmrun_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_pmrun_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_PMRUN_EXE - become_flags: - description: Options to pass to pmrun. - type: string - default: '' - ini: - - section: privilege_escalation - key: become_flags - - section: pmrun_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_pmrun_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_PMRUN_FLAGS - become_pass: - description: pmrun password. - type: string - required: false - vars: - - name: ansible_become_password - - name: ansible_become_pass - - name: ansible_pmrun_pass - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_PMRUN_PASS - ini: - - section: pmrun_become_plugin - key: password - notes: - - This plugin ignores the become_user supplied and uses pmrun's own configuration to select the user. -''' +DOCUMENTATION = r""" +name: pmrun +short_description: Privilege Manager run +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(pmrun) utility. +author: Ansible Core Team +options: + become_exe: + description: C(pmrun) executable. + type: string + default: pmrun + ini: + - section: privilege_escalation + key: become_exe + - section: pmrun_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_pmrun_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_PMRUN_EXE + become_flags: + description: Options to pass to C(pmrun). + type: string + default: '' + ini: + - section: privilege_escalation + key: become_flags + - section: pmrun_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_pmrun_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_PMRUN_FLAGS + become_pass: + description: C(pmrun) password. + type: string + required: false + vars: + - name: ansible_become_password + - name: ansible_become_pass + - name: ansible_pmrun_pass + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_PMRUN_PASS + ini: + - section: pmrun_become_plugin + key: password +notes: + - This plugin ignores the C(become_user) supplied and uses C(pmrun)'s own configuration to select the user. +""" from ansible.plugins.become import BecomeBase from ansible.module_utils.six.moves import shlex_quote diff --git a/plugins/become/run0.py b/plugins/become/run0.py index a718e86f24..0c0d6bfffb 100644 --- a/plugins/become/run0.py +++ b/plugins/become/run0.py @@ -7,68 +7,68 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ - name: run0 - short_description: Systemd's run0 - description: - - This become plugins allows your remote/login user to execute commands as another user via the C(run0) utility. - author: - - Thomas Sjögren (@konstruktoid) - version_added: '9.0.0' - options: - become_user: - description: User you 'become' to execute the task. - default: root - ini: - - section: privilege_escalation - key: become_user - - section: run0_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_run0_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_RUN0_USER - type: string - become_exe: - description: The C(run0) executable. - default: run0 - ini: - - section: privilege_escalation - key: become_exe - - section: run0_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_run0_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_RUN0_EXE - type: string - become_flags: - description: Options to pass to run0. - default: '' - ini: - - section: privilege_escalation - key: become_flags - - section: run0_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_run0_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_RUN0_FLAGS - type: string - notes: - - This plugin will only work when a polkit rule is in place. +DOCUMENTATION = r""" +name: run0 +short_description: Systemd's run0 +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(run0) utility. +author: + - Thomas Sjögren (@konstruktoid) +version_added: '9.0.0' +options: + become_user: + description: User you 'become' to execute the task. + default: root + ini: + - section: privilege_escalation + key: become_user + - section: run0_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_run0_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_RUN0_USER + type: string + become_exe: + description: C(run0) executable. + default: run0 + ini: + - section: privilege_escalation + key: become_exe + - section: run0_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_run0_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_RUN0_EXE + type: string + become_flags: + description: Options to pass to C(run0). + default: '' + ini: + - section: privilege_escalation + key: become_flags + - section: run0_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_run0_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_RUN0_FLAGS + type: string +notes: + - This plugin will only work when a C(polkit) rule is in place. """ EXAMPLES = r""" # An example polkit rule that allows the user 'ansible' in the 'wheel' group # to execute commands using run0 without authentication. -/etc/polkit-1/rules.d/60-run0-fast-user-auth.rules: | +/etc/polkit-1/rules.d/60-run0-fast-user-auth.rules: |- polkit.addRule(function(action, subject) { if(action.id == "org.freedesktop.systemd1.manage-units" && subject.isInGroup("wheel") && diff --git a/plugins/become/sesu.py b/plugins/become/sesu.py index 08dfdfca54..6fe64e41f8 100644 --- a/plugins/become/sesu.py +++ b/plugins/become/sesu.py @@ -5,73 +5,73 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: sesu - short_description: CA Privileged Access Manager - description: - - This become plugins allows your remote/login user to execute commands as another user via the sesu utility. - author: ansible (@nekonyuu) - options: - become_user: - description: User you 'become' to execute the task. - type: string - default: '' - ini: - - section: privilege_escalation - key: become_user - - section: sesu_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_sesu_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_SESU_USER - become_exe: - description: sesu executable. - type: string - default: sesu - ini: - - section: privilege_escalation - key: become_exe - - section: sesu_become_plugin - key: executable - vars: - - name: ansible_become_exe - - name: ansible_sesu_exe - env: - - name: ANSIBLE_BECOME_EXE - - name: ANSIBLE_SESU_EXE - become_flags: - description: Options to pass to sesu. - type: string - default: -H -S -n - ini: - - section: privilege_escalation - key: become_flags - - section: sesu_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_sesu_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_SESU_FLAGS - become_pass: - description: Password to pass to sesu. - type: string - required: false - vars: - - name: ansible_become_password - - name: ansible_become_pass - - name: ansible_sesu_pass - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_SESU_PASS - ini: - - section: sesu_become_plugin - key: password -''' +DOCUMENTATION = r""" +name: sesu +short_description: CA Privileged Access Manager +description: + - This become plugins allows your remote/login user to execute commands as another user using the C(sesu) utility. +author: ansible (@nekonyuu) +options: + become_user: + description: User you 'become' to execute the task. + type: string + default: '' + ini: + - section: privilege_escalation + key: become_user + - section: sesu_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_sesu_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_SESU_USER + become_exe: + description: C(sesu) executable. + type: string + default: sesu + ini: + - section: privilege_escalation + key: become_exe + - section: sesu_become_plugin + key: executable + vars: + - name: ansible_become_exe + - name: ansible_sesu_exe + env: + - name: ANSIBLE_BECOME_EXE + - name: ANSIBLE_SESU_EXE + become_flags: + description: Options to pass to C(sesu). + type: string + default: -H -S -n + ini: + - section: privilege_escalation + key: become_flags + - section: sesu_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_sesu_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_SESU_FLAGS + become_pass: + description: Password to pass to C(sesu). + type: string + required: false + vars: + - name: ansible_become_password + - name: ansible_become_pass + - name: ansible_sesu_pass + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_SESU_PASS + ini: + - section: sesu_become_plugin + key: password +""" from ansible.plugins.become import BecomeBase diff --git a/plugins/become/sudosu.py b/plugins/become/sudosu.py index 5dae85a192..fe85c9ee91 100644 --- a/plugins/become/sudosu.py +++ b/plugins/become/sudosu.py @@ -5,74 +5,75 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = """ - name: sudosu - short_description: Run tasks using sudo su - +DOCUMENTATION = r""" +name: sudosu +short_description: Run tasks using sudo su - +description: + - This become plugin allows your remote/login user to execute commands as another user using the C(sudo) and C(su) utilities + combined. +author: + - Dag Wieers (@dagwieers) +version_added: 2.4.0 +options: + become_user: + description: User you 'become' to execute the task. + type: string + default: root + ini: + - section: privilege_escalation + key: become_user + - section: sudo_become_plugin + key: user + vars: + - name: ansible_become_user + - name: ansible_sudo_user + env: + - name: ANSIBLE_BECOME_USER + - name: ANSIBLE_SUDO_USER + become_flags: + description: Options to pass to C(sudo). + type: string + default: -H -S -n + ini: + - section: privilege_escalation + key: become_flags + - section: sudo_become_plugin + key: flags + vars: + - name: ansible_become_flags + - name: ansible_sudo_flags + env: + - name: ANSIBLE_BECOME_FLAGS + - name: ANSIBLE_SUDO_FLAGS + become_pass: + description: Password to pass to C(sudo). + type: string + required: false + vars: + - name: ansible_become_password + - name: ansible_become_pass + - name: ansible_sudo_pass + env: + - name: ANSIBLE_BECOME_PASS + - name: ANSIBLE_SUDO_PASS + ini: + - section: sudo_become_plugin + key: password + alt_method: description: - - This become plugin allows your remote/login user to execute commands as another user via the C(sudo) and C(su) utilities combined. - author: - - Dag Wieers (@dagwieers) - version_added: 2.4.0 - options: - become_user: - description: User you 'become' to execute the task. - type: string - default: root - ini: - - section: privilege_escalation - key: become_user - - section: sudo_become_plugin - key: user - vars: - - name: ansible_become_user - - name: ansible_sudo_user - env: - - name: ANSIBLE_BECOME_USER - - name: ANSIBLE_SUDO_USER - become_flags: - description: Options to pass to C(sudo). - type: string - default: -H -S -n - ini: - - section: privilege_escalation - key: become_flags - - section: sudo_become_plugin - key: flags - vars: - - name: ansible_become_flags - - name: ansible_sudo_flags - env: - - name: ANSIBLE_BECOME_FLAGS - - name: ANSIBLE_SUDO_FLAGS - become_pass: - description: Password to pass to C(sudo). - type: string - required: false - vars: - - name: ansible_become_password - - name: ansible_become_pass - - name: ansible_sudo_pass - env: - - name: ANSIBLE_BECOME_PASS - - name: ANSIBLE_SUDO_PASS - ini: - - section: sudo_become_plugin - key: password - alt_method: - description: - - Whether to use an alternative method to call C(su). Instead of running C(su -l user /path/to/shell -c command), - it runs C(su -l user -c command). - - Use this when the default one is not working on your system. - required: false - type: boolean - ini: - - section: community.general.sudosu - key: alternative_method - vars: - - name: ansible_sudosu_alt_method - env: - - name: ANSIBLE_SUDOSU_ALT_METHOD - version_added: 9.2.0 + - Whether to use an alternative method to call C(su). Instead of running C(su -l user /path/to/shell -c command), it + runs C(su -l user -c command). + - Use this when the default one is not working on your system. + required: false + type: boolean + ini: + - section: community.general.sudosu + key: alternative_method + vars: + - name: ansible_sudosu_alt_method + env: + - name: ANSIBLE_SUDOSU_ALT_METHOD + version_added: 9.2.0 """