centersl/ansible-docs
1
0
Fork 0
mirror of https://github.com/ansible/ansible-documentation.git synced 2026-03-27 13:28:51 +07:00
Code Issues Packages Projects Releases Wiki Activity

Use new :ansoptref: and :ansretvalref: roles. (#3306) (#3312)

Browse Source 
(cherry picked from commit daef4fd8c4)

Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
patchback[bot]
2025-11-26 22:32:16 +01:00
committed by GitHub
parent c8ad7f5058
commit da32946ff6
3 changed files with 38 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/docsite/rst/dev_guide/developing_program_flow_modules.rst
View File

@@ -502,8 +502,8 @@ Modules can access this parameter by using the public ``tmpdir`` property. The `
The directory name is generated randomly, and the the root of the directory is determined by one of these:
* :ref:`DEFAULT_LOCAL_TMP`
* `remote_tmp <https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-remote_tmp>`_
* `system_tmpdirs <https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-system_tmpdirs>`_
* :ansoptref:`remote_tmp <ansible.builtin.sh#shell:remote_tmp>`
* :ansoptref:`system_tmpdirs <ansible.builtin.sh#shell:system_tmpdirs>`
As a result, using the ``ansible.cfg`` configuration file to activate or customize this setting will not guarantee that you control the full value.
@@ -511,7 +511,7 @@ As a result, using the ``ansible.cfg`` configuration file to activate or customi
_ansible_remote_tmp
^^^^^^^^^^^^^^^^^^^
The module's ``tmpdir`` property creates a randomized directory name in this directory if the action plugin did not set ``_ansible_tmpdir``. For more details, see the `remote_tmp <https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-remote_tmp>`_ parameter of the shell plugin.
The module's ``tmpdir`` property creates a randomized directory name in this directory if the action plugin did not set ``_ansible_tmpdir``. For more details, see the :ansoptref:`remote_tmp <ansible.builtin.sh#shell:remote_tmp>` parameter of the shell plugin.
.. _flow_module_return_values:

40
docs/docsite/rst/dev_guide/style_guide/index.rst
View File

@@ -251,7 +251,10 @@ Instead of ``#module``, you can also specify ``#<plugin_type>`` to reference to
Adding links to module and plugin options and return values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use the ``:ansopt:`` and ``:ansretval:`` roles to reference options and return values of modules and plugins:
Use the ``:ansopt:`` and ``:ansretval:`` roles to reference options and return values of modules and plugins while showing the option's resp. return value's name and optionally a value.
Use the ``:ansoptref:`` and ``:ansretvalref:`` roles to reference options and return values of modules and plugins while displaying a provided title.
The following example shows their usage:
.. code-block:: rst
@@ -259,6 +262,10 @@ Use the ``:ansopt:`` and ``:ansretval:`` roles to reference options and return v
``ansible.builtin.file`` module; :ansopt:`ansible.builtin.file#module:path=/root/.ssh/known_hosts`
shows the assignment ``path=/root/.ssh/known_hosts`` as a clickable link.
You can :ansoptref:`provide a path <ansible.builtin.file#module:path>`
to the :ansplugin:`ansible.builtin.file#module`; its value is
:ansretvalref:`returned as a return value <ansible.builtin.file#module:path>`.
:ansretval:`ansible.builtin.stat#module:stat.exists` references the ``stat.exists`` return value
of the ``ansible.builtin.stat`` module. You can also use ``=`` as for option values:
:ansretval:`ansible.builtin.stat#module:stat.exists=true` shows ``stat.exists=true``.
@@ -267,21 +274,26 @@ Use the ``:ansopt:`` and ``:ansretval:`` roles to reference options and return v
assignment without a link; the same is true for return values: :ansretval:`foo` and
:ansretval:`foo=bar`.
This displays as
":ansopt:`ansible.builtin.file#module:path` references the ``path`` parameter of the
``ansible.builtin.file`` module; :ansopt:`ansible.builtin.file#module:path=/root/.ssh/known_hosts`
shows the assignment ``path=/root/.ssh/known_hosts`` as a clickable link."
and
":ansretval:`ansible.builtin.stat#module:stat.exists` references the ``stat.exists`` return value
of the ``ansible.builtin.stat`` module. You can also use ``=`` as for option values:
:ansretval:`ansible.builtin.stat#module:stat.exists=true` shows ``stat.exists=true``."
and
":ansopt:`foo` and :ansopt:`foo=bar` use the same markup for an option and an option
assignment without a link; the same is true for return values: :ansretval:`foo` and
:ansretval:`foo=bar`.".
This displays as:
:ansopt:`ansible.builtin.file#module:path` references the ``path`` parameter of the
``ansible.builtin.file`` module; :ansopt:`ansible.builtin.file#module:path=/root/.ssh/known_hosts`
shows the assignment ``path=/root/.ssh/known_hosts`` as a clickable link.
You can :ansoptref:`provide a path <ansible.builtin.file#module:path>`
to the :ansplugin:`ansible.builtin.file#module`; its value is
:ansretvalref:`returned as a return value <ansible.builtin.file#module:path>`.
:ansretval:`ansible.builtin.stat#module:stat.exists` references the ``stat.exists`` return value
of the ``ansible.builtin.stat`` module. You can also use ``=`` as for option values:
:ansretval:`ansible.builtin.stat#module:stat.exists=true` shows ``stat.exists=true``.
:ansopt:`foo` and :ansopt:`foo=bar` use the same markup for an option and an option
assignment without a link; the same is true for return values: :ansretval:`foo` and
:ansretval:`foo=bar`.
For both option and return values, ``.`` is used to reference suboptions and contained return values.
Array stubs (``[...]``) can be used to indicate that something is a list, for example the ``:retval:``
Array stubs (``[...]``) can be used to indicate that something is a list, for example the ``:ansretval:``
argument ``ansible.builtin.service_facts#module:ansible_facts.services['systemd'].state`` references
the ``ansible_facts.services.state`` return value of the ``ansible.builtin.service_facts`` module
(:ansretval:`ansible.builtin.service_facts#module:ansible_facts.services['systemd'].state`).

17
docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst
View File

@@ -172,8 +172,9 @@ to check ``world_readable_temp`` per below.
If ``ansible_common_remote_group`` is **not** set and the chown above it failed,
or if ``ansible_common_remote_group`` *is* set but the :command:`chgrp` (or
following group-permissions :command:`chmod`) returned a non-successful exit
code, Ansible will lastly check `the world_readable_temp option`_. If this is
set, Ansible will place the module file in a world-readable temporary directory,
code, Ansible will lastly check
:ansoptref:`the world_readable_temp option <ansible.builtin.sh#shell:world_readable_temp>`.
If this is set, Ansible will place the module file in a world-readable temporary directory,
with world-readable permissions to allow the ``become_user`` (and incidentally
any other user on the system) to read the contents of the file. **If any of the
parameters passed to the module are sensitive in nature, and you do not trust
@@ -198,8 +199,9 @@ Several ways exist to avoid the above logic flow entirely:
.. warning:: Although the Solaris ZFS filesystem has filesystem ACLs, the ACLs
are not POSIX.1e filesystem acls (they are NFSv4 ACLs instead). Ansible
cannot use these ACLs to manage its temp file permissions so you may have
to resort to `the world_readable_temp option`_ if the remote machines
use ZFS.
to resort to
:ansoptref:`the world_readable_temp option <ansible.builtin.sh#shell:world_readable_temp>`
if the remote machines use ZFS.
.. versionchanged:: 2.1
@@ -208,13 +210,12 @@ Ansible defaults to issuing an error if it cannot execute securely with ``become
If you cannot use pipelining or POSIX ACLs, must connect as an unprivileged user,
must use ``become`` to execute as a different unprivileged user,
and decide that your managed nodes are secure enough for the
modules you want to run there to be world readable, you can turn on `the world_readable_temp option`_, which will change this from an error into
a warning and allow the task to run as it did prior to 2.1.
modules you want to run there to be world readable, you can turn on
:ansoptref:`the world_readable_temp option <ansible.builtin.sh#shell:world_readable_temp>`,
which will change this from an error into a warning and allow the task to run as it did prior to 2.1.
.. versionchanged:: 2.10
.. _the world_readable_temp option: https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-world_readable_temp
Ansible 2.10 introduces the above-mentioned ``ansible_common_remote_group``
fallback. As mentioned above, if enabled, it is used when ``remote_user`` and
``become_user`` are both unprivileged users. Refer to the text above for details