diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst index 77b223ccd9d..26d8e0cba3c 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -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 `_ -* `system_tmpdirs `_ +* :ansoptref:`remote_tmp ` +* :ansoptref:`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 `_ 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 ` parameter of the shell plugin. .. _flow_module_return_values: diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst index f89721e8598..efb1733e394 100644 --- a/docs/docsite/rst/dev_guide/style_guide/index.rst +++ b/docs/docsite/rst/dev_guide/style_guide/index.rst @@ -251,7 +251,10 @@ Instead of ``#module``, you can also specify ``#`` 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 ` + to the :ansplugin:`ansible.builtin.file#module`; its value is + :ansretvalref:`returned as a return value `. + :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 ` + to the :ansplugin:`ansible.builtin.file#module`; its value is + :ansretvalref:`returned as a return value `. + + :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`). diff --git a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst index c6ea70f9645..506487abc1e 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst @@ -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 `. +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 ` + 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 `, +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