1.. _common_return_values: 2 3Return Values 4------------- 5 6.. contents:: Topics 7 8Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by 9the `ansible` program. Each module can optionally document its own unique return values (visible through ansible-doc and on the :ref:`main docsite<ansible_documentation>`). 10 11This document covers return values common to all modules. 12 13.. note:: Some of these keys might be set by Ansible itself once it processes the module's return information. 14 15 16Common 17^^^^^^ 18 19backup_file 20``````````` 21For those modules that implement `backup=no|yes` when manipulating files, a path to the backup file created. 22 23 .. code-block:: console 24 25 "backup_file": "./foo.txt.32729.2020-07-30@06:24:19~" 26 27 28changed 29``````` 30A boolean indicating if the task had to make changes. 31 32 .. code-block:: console 33 34 "changed": true 35 36diff 37```` 38Information on differences between the previous and current state. Often a dictionary with entries ``before`` and ``after``, which will then be formatted by the callback plugin to a diff view. 39 40 .. code-block:: console 41 42 "diff": [ 43 { 44 "after": "", 45 "after_header": "foo.txt (content)", 46 "before": "", 47 "before_header": "foo.txt (content)" 48 }, 49 { 50 "after_header": "foo.txt (file attributes)", 51 "before_header": "foo.txt (file attributes)" 52 } 53 54failed 55`````` 56A boolean that indicates if the task was failed or not. 57 58 .. code-block:: console 59 60 "failed": false 61 62invocation 63`````````` 64Information on how the module was invoked. 65 66 .. code-block:: console 67 68 "invocation": { 69 "module_args": { 70 "_original_basename": "foo.txt", 71 "attributes": null, 72 "backup": true, 73 "checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709", 74 "content": null, 75 "delimiter": null, 76 "dest": "./foo.txt", 77 "directory_mode": null, 78 "follow": false, 79 "force": true, 80 "group": null, 81 "local_follow": null, 82 "mode": "666", 83 "owner": null, 84 "regexp": null, 85 "remote_src": null, 86 "selevel": null, 87 "serole": null, 88 "setype": null, 89 "seuser": null, 90 "src": "/Users/foo/.ansible/tmp/ansible-tmp-1596115458.110205-105717464505158/source", 91 "unsafe_writes": null, 92 "validate": null 93 } 94 95msg 96``` 97A string with a generic message relayed to the user. 98 99 .. code-block:: console 100 101 "msg": "line added" 102 103rc 104`` 105Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains 'return code' of these utilities. 106 107 .. code-block:: console 108 109 "rc": 257 110 111results 112``````` 113If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module 'result' per item. 114 115 .. code-block:: console 116 117 "results": [ 118 { 119 "ansible_loop_var": "item", 120 "backup": "foo.txt.83170.2020-07-30@07:03:05~", 121 "changed": true, 122 "diff": [ 123 { 124 "after": "", 125 "after_header": "foo.txt (content)", 126 "before": "", 127 "before_header": "foo.txt (content)" 128 }, 129 { 130 "after_header": "foo.txt (file attributes)", 131 "before_header": "foo.txt (file attributes)" 132 } 133 ], 134 "failed": false, 135 "invocation": { 136 "module_args": { 137 "attributes": null, 138 "backrefs": false, 139 "backup": true 140 } 141 }, 142 "item": "foo", 143 "msg": "line added" 144 }, 145 { 146 "ansible_loop_var": "item", 147 "backup": "foo.txt.83187.2020-07-30@07:03:05~", 148 "changed": true, 149 "diff": [ 150 { 151 "after": "", 152 "after_header": "foo.txt (content)", 153 "before": "", 154 "before_header": "foo.txt (content)" 155 }, 156 { 157 "after_header": "foo.txt (file attributes)", 158 "before_header": "foo.txt (file attributes)" 159 } 160 ], 161 "failed": false, 162 "invocation": { 163 "module_args": { 164 "attributes": null, 165 "backrefs": false, 166 "backup": true 167 } 168 }, 169 "item": "bar", 170 "msg": "line added" 171 } 172 ] 173 174skipped 175``````` 176A boolean that indicates if the task was skipped or not 177 178 .. code-block:: console 179 180 "skipped": true 181 182stderr 183`````` 184Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains the error output of these utilities. 185 186 .. code-block:: console 187 188 "stderr": "ls: foo: No such file or directory" 189 190stderr_lines 191```````````` 192When `stderr` is returned we also always provide this field which is a list of strings, one item per line from the original. 193 194 .. code-block:: console 195 196 "stderr_lines": [ 197 "ls: doesntexist: No such file or directory" 198 ] 199 200stdout 201`````` 202Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on). This field contains the normal output of these utilities. 203 204 .. code-block:: console 205 206 "stdout": "foo!" 207 208stdout_lines 209```````````` 210When `stdout` is returned, Ansible always provides a list of strings, each containing one item per line from the original output. 211 212 .. code-block:: console 213 214 "stdout_lines": [ 215 "foo!" 216 ] 217 218 219.. _internal_return_values: 220 221Internal use 222^^^^^^^^^^^^ 223 224These keys can be added by modules but will be removed from registered variables; they are 'consumed' by Ansible itself. 225 226ansible_facts 227````````````` 228This key should contain a dictionary which will be appended to the facts assigned to the host. These will be directly accessible and don't require using a registered variable. 229 230exception 231````````` 232This key can contain traceback information caused by an exception in a module. It will only be displayed on high verbosity (-vvv). 233 234warnings 235```````` 236This key contains a list of strings that will be presented to the user. 237 238deprecations 239```````````` 240This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are `msg` and `version`, values are string, value for the `version` key can be an empty string. 241 242.. seealso:: 243 244 :ref:`list_of_collections` 245 Browse existing collections, modules, and plugins 246 `GitHub modules directory <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ 247 Browse source of core and extras modules 248 `Mailing List <https://groups.google.com/group/ansible-devel>`_ 249 Development mailing list 250 `irc.libera.chat <https://libera.chat/>`_ 251 #ansible IRC chat channel 252